mingw/info/gdb/Set-Breaks.html

   1 <html lang="en">
   2 <head>
   3 <title>Debugging with GDB</title>
   4 <meta http-equiv="Content-Type" content="text/html">
   5 <meta name="description" content="Debugging with GDB">
   6 <meta name="generator" content="makeinfo 4.3">
   7 <link href="http://www.gnu.org/software/texinfo/" rel="generator-home">
   8 </head>
   9 <body>
  10 <div class="node">
  11 <p>
  12 Node:<a name="Set%20Breaks">Set Breaks</a>,
  13 Next:<a rel="next" accesskey="n" href="Set-Watchpoints.html#Set%20Watchpoints">Set Watchpoints</a>,
  14 Up:<a rel="up" accesskey="u" href="Breakpoints.html#Breakpoints">Breakpoints</a>
  15 <hr><br>
  16 </div>
  17
  18 <h4 class="subsection">Setting breakpoints</h4>
  19
  20    <p>Breakpoints are set with the <code>break</code> command (abbreviated
  21 <code>b</code>).  The debugger convenience variable <code>$bpnum</code> records the
  22 number of the breakpoint you've set most recently; see <a href="Convenience-Vars.html#Convenience%20Vars">Convenience variables</a>, for a discussion of what you can do with
  23 convenience variables.
  24
  25    <p>You have several ways to say where the breakpoint should go.
  26
  27      <dl>
  28 <dt><code>break </code><var>function</var><code></code>
  29      <dd>Set a breakpoint at entry to function <var>function</var>.
  30 When using source languages that permit overloading of symbols, such as
  31 C<tt>++</tt>, <var>function</var> may refer to more than one possible place to break.
  32 See <a href="Breakpoint-Menus.html#Breakpoint%20Menus">Breakpoint menus</a>, for a discussion of that situation.
  33
  34      <br><dt><code>break +</code><var>offset</var><code></code>
  35      <dd><dt><code>break -</code><var>offset</var><code></code>
  36      <dd>Set a breakpoint some number of lines forward or back from the position
  37 at which execution stopped in the currently selected <dfn>stack frame</dfn>.
  38 (See <a href="Frames.html#Frames">Frames</a>, for a description of stack frames.)
  39
  40      <br><dt><code>break </code><var>linenum</var><code></code>
  41      <dd>Set a breakpoint at line <var>linenum</var> in the current source file.
  42 The current source file is the last file whose source text was printed.
  43 The breakpoint will stop your program just before it executes any of the
  44 code on that line.
  45
  46      <br><dt><code>break </code><var>filename</var><code>:</code><var>linenum</var><code></code>
  47      <dd>Set a breakpoint at line <var>linenum</var> in source file <var>filename</var>.
  48
  49      <br><dt><code>break </code><var>filename</var><code>:</code><var>function</var><code></code>
  50      <dd>Set a breakpoint at entry to function <var>function</var> found in file
  51 <var>filename</var>.  Specifying a file name as well as a function name is
  52 superfluous except when multiple files contain similarly named
  53 functions.
  54
  55      <br><dt><code>break *</code><var>address</var><code></code>
  56      <dd>Set a breakpoint at address <var>address</var>.  You can use this to set
  57 breakpoints in parts of your program which do not have debugging
  58 information or source files.
  59
  60      <br><dt><code>break</code>
  61      <dd>When called without any arguments, <code>break</code> sets a breakpoint at
  62 the next instruction to be executed in the selected stack frame
  63 (see <a href="Stack.html#Stack">Examining the Stack</a>).  In any selected frame but the
  64 innermost, this makes your program stop as soon as control
  65 returns to that frame.  This is similar to the effect of a
  66 <code>finish</code> command in the frame inside the selected frame--except
  67 that <code>finish</code> does not leave an active breakpoint.  If you use
  68 <code>break</code> without an argument in the innermost frame, GDB stops
  69 the next time it reaches the current location; this may be useful
  70 inside loops.
  71
  72      GDB normally ignores breakpoints when it resumes execution, until at
  73 least one instruction has been executed.  If it did not do this, you
  74 would be unable to proceed past a breakpoint without first disabling the
  75 breakpoint.  This rule applies whether or not the breakpoint already
  76 existed when your program stopped.
  77
  78      <br><dt><code>break ... if </code><var>cond</var><code></code>
  79      <dd>Set a breakpoint with condition <var>cond</var>; evaluate the expression
  80 <var>cond</var> each time the breakpoint is reached, and stop only if the
  81 value is nonzero--that is, if <var>cond</var> evaluates as true.
  82 <code>...</code> stands for one of the possible arguments described
  83 above (or no argument) specifying where to break.  See <a href="Conditions.html#Conditions">Break conditions</a>, for more information on breakpoint conditions.
  84
  85      <br><dt><code>tbreak </code><var>args</var><code></code>
  86      <dd>Set a breakpoint enabled only for one stop.  <var>args</var> are the
  87 same as for the <code>break</code> command, and the breakpoint is set in the same
  88 way, but the breakpoint is automatically deleted after the first time your
  89 program stops there.  See <a href="Disabling.html#Disabling">Disabling breakpoints</a>.
  90
  91      <br><dt><code>hbreak </code><var>args</var><code></code>
  92      <dd>Set a hardware-assisted breakpoint.  <var>args</var> are the same as for the
  93 <code>break</code> command and the breakpoint is set in the same way, but the
  94 breakpoint requires hardware support and some target hardware may not
  95 have this support.  The main purpose of this is EPROM/ROM code
  96 debugging, so you can set a breakpoint at an instruction without
  97 changing the instruction.  This can be used with the new trap-generation
  98 provided by SPARClite DSU and some x86-based targets.  These targets
  99 will generate traps when a program accesses some data or instruction
 100 address that is assigned to the debug registers.  However the hardware
 101 breakpoint registers can take a limited number of breakpoints.  For
 102 example, on the DSU, only two data breakpoints can be set at a time, and
 103 GDB will reject this command if more than two are used.  Delete
 104 or disable unused hardware breakpoints before setting new ones
 105 (see <a href="Disabling.html#Disabling">Disabling</a>).  See <a href="Conditions.html#Conditions">Break conditions</a>.
 106
 107      <br><dt><code>thbreak </code><var>args</var><code></code>
 108      <dd>Set a hardware-assisted breakpoint enabled only for one stop.  <var>args</var>
 109 are the same as for the <code>hbreak</code> command and the breakpoint is set in
 110 the same way.  However, like the <code>tbreak</code> command,
 111 the breakpoint is automatically deleted after the
 112 first time your program stops there.  Also, like the <code>hbreak</code>
 113 command, the breakpoint requires hardware support and some target hardware
 114 may not have this support.  See <a href="Disabling.html#Disabling">Disabling breakpoints</a>.
 115 See also <a href="Conditions.html#Conditions">Break conditions</a>.
 116
 117      <br><dt><code>rbreak </code><var>regex</var><code></code>
 118      <dd>Set breakpoints on all functions matching the regular expression
 119 <var>regex</var>.  This command sets an unconditional breakpoint on all
 120 matches, printing a list of all breakpoints it set.  Once these
 121 breakpoints are set, they are treated just like the breakpoints set with
 122 the <code>break</code> command.  You can delete them, disable them, or make
 123 them conditional the same way as any other breakpoint.
 124
 125      <p>The syntax of the regular expression is the standard one used with tools
 126 like <code>grep</code>.  Note that this is different from the syntax used by
 127 shells, so for instance <code>foo*</code> matches all functions that include
 128 an <code>fo</code> followed by zero or more <code>o</code>s.  There is an implicit
 129 <code>.*</code> leading and trailing the regular expression you supply, so to
 130 match only functions that begin with <code>foo</code>, use <code>^foo</code>.
 131
 132      <p>When debugging C<tt>++</tt> programs, <code>rbreak</code> is useful for setting
 133 breakpoints on overloaded functions that are not members of any special
 134 classes.
 135
 136      <br><dt><code>info breakpoints </code>[<code></code><var>n</var><code></code>]<code></code>
 137      <dd><dt><code>info break </code>[<code></code><var>n</var><code></code>]<code></code>
 138      <dd><dt><code>info watchpoints </code>[<code></code><var>n</var><code></code>]<code></code>
 139      <dd>Print a table of all breakpoints, watchpoints, and catchpoints set and
 140 not deleted, with the following columns for each breakpoint:
 141
 142           <dl>
 143 <dt><em>Breakpoint Numbers</em>
 144           <dd><br><dt><em>Type</em>
 145           <dd>Breakpoint, watchpoint, or catchpoint.
 146 <br><dt><em>Disposition</em>
 147           <dd>Whether the breakpoint is marked to be disabled or deleted when hit.
 148 <br><dt><em>Enabled or Disabled</em>
 149           <dd>Enabled breakpoints are marked with <code>y</code>.  <code>n</code> marks breakpoints
 150 that are not enabled.
 151 <br><dt><em>Address</em>
 152           <dd>Where the breakpoint is in your program, as a memory address.
 153 <br><dt><em>What</em>
 154           <dd>Where the breakpoint is in the source for your program, as a file and
 155 line number.
 156 </dl>
 157
 158      <p>If a breakpoint is conditional, <code>info break</code> shows the condition on
 159 the line following the affected breakpoint; breakpoint commands, if any,
 160 are listed after that.
 161
 162      <p><code>info break</code> with a breakpoint
 163 number <var>n</var> as argument lists only that breakpoint.  The
 164 convenience variable <code>$_</code> and the default examining-address for
 165 the <code>x</code> command are set to the address of the last breakpoint
 166 listed (see <a href="Memory.html#Memory">Examining memory</a>).
 167
 168      <p><code>info break</code> displays a count of the number of times the breakpoint
 169 has been hit.  This is especially useful in conjunction with the
 170 <code>ignore</code> command.  You can ignore a large number of breakpoint
 171 hits, look at the breakpoint info to see how many times the breakpoint
 172 was hit, and then run again, ignoring one less than that number.  This
 173 will get you quickly to the last hit of that breakpoint.
 174 </dl>
 175
 176    GDB allows you to set any number of breakpoints at the same place in
 177 your program.  There is nothing silly or meaningless about this.  When
 178 the breakpoints are conditional, this is even useful
 179 (see <a href="Conditions.html#Conditions">Break conditions</a>).
 180
 181    GDB itself sometimes sets breakpoints in your program for
 182 special purposes, such as proper handling of <code>longjmp</code> (in C
 183 programs).  These internal breakpoints are assigned negative numbers,
 184 starting with <code>-1</code>; <code>info breakpoints</code> does not display them.
 185 You can see these breakpoints with the GDB maintenance command
 186 <code>maint info breakpoints</code> (see <a href="maint-info-breakpoints.html#maint%20info%20breakpoints">maint info breakpoints</a>).
 187
 188    </body></html>
 189