Setting breakpoints

Use the break (b) command to set breakpoints.

The debugger convenience variable $bpnum records the number of the breakpoints you've set most recently; see "Convenience variables" for a discussion of what you can do with convenience variables.

You have several ways to say where the breakpoint should go:

break function
Set a breakpoint at entry to function. When using source languages such as C++ that permit overloading of symbols, function may refer to more than one possible place to break. See "Breakpoint menus" for a discussion of that situation.
break +offset or break -offset
Set a breakpoint some number of lines forward or back from the position at which execution stopped in the currently selected frame.
break linenum
Set a breakpoint at line linenum in the current source file. That file is the last file whose source text was printed. This breakpoint stops your program just before it executes any of the code on that line.
break filename:linenum
Set a breakpoint at line linenum in source file filename.
break filename:function
Set a breakpoint at entry to function found in file filename. Specifying a filename as well as a function name is superfluous except when multiple files contain similarly named functions.
break *address
Set a breakpoint at address address. You can use this to set breakpoints in parts of your program that don't have debugging information or source files.
When called without any arguments, break sets a breakpoint at the next instruction to be executed in the selected stack frame (see "Examining the Stack"). 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 finish command in the frame inside the selected frame—except that finish doesn't leave an active breakpoint. If you use break without an argument in the innermost frame, GDB stops the next time it reaches the current location; this may be useful inside loops.

GDB normally ignores breakpoints when it resumes execution, until at least one instruction has been executed. If it didn't do this, you wouldn't be able to proceed past a breakpoint without first disabling the breakpoint. This rule applies whether or not the breakpoint already existed when your program stopped.

break ... if cond
Set a breakpoint with condition cond; evaluate the expression cond each time the breakpoint is reached, and stop only if the value is nonzero—that is, if cond evaluates as true. The ellipsis (...) stands for one of the possible arguments described above (or no argument) specifying where to break. For more information on breakpoint conditions, see "Break conditions."

There are several variations on the break command, all using the same syntax as above:

Set a breakpoint enabled only for one stop. The breakpoint is set in the same way as for the break command, except that it's automatically deleted after the first time your program stops there. See "Disabling breakpoints."
Set a hardware-assisted breakpoint. The breakpoint is set in the same way as for the break command, except that it 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.

Set a hardware-assisted breakpoint enabled only for one stop. The breakpoint is set in the same way as for the break command. However, like the tbreak command, the breakpoint is automatically deleted after the first time your program stops there. Also, like the hbreak command, the breakpoint requires hardware support, which some target hardware may not have. See "Disabling breakpoints" and "Break conditions."
rbreak regex
Set breakpoints on all functions matching the regular expression regex. This command sets an unconditional breakpoint on all matches, printing a list of all breakpoints it set. Once these breakpoints are set, they're treated just like the breakpoints set with the break command. You can delete them, disable them, or make them conditional the same way as any other breakpoint.

When debugging you're C++ programs, rbreak is useful for setting breakpoints on overloaded functions that aren't members of any special classes.

The following commands display information about breakpoints and watchpoints:

info breakpoints [n] or info break [n] or info watchpoints [n]
Print a table of all breakpoints and watchpoints set and not deleted, with the following columns for each breakpoint:
  • Breakpoint Numbers.
  • Type — breakpoint or watchpoint.
  • Disposition — whether the breakpoint is marked to be disabled or deleted when hit.
  • Enabled or Disabled — enabled breakpoints are marked with y, disabled with n.
  • Address — where the breakpoint is in your program, as a memory address.
  • What — where the breakpoint is in the source for your program, as a file and line number.

If a breakpoint is conditional, info break shows the condition on the line following the affected breakpoint; breakpoint commands, if any, are listed after that.

An info break command with a breakpoint number n as argument lists only that breakpoint. The convenience variable $_ and the default examining-address for the x command are set to the address of the last breakpoint listed (see "Examining memory").

The info break command displays the number of times the breakpoint has been hit. This is especially useful in conjunction with the ignore command. You can ignore a large number of breakpoint hits, look at the breakpoint information to see how many times the breakpoint was hit, and then run again, ignoring one less than that number. This gets you quickly to the last hit of that breakpoint.

GDB lets you set any number of breakpoints at the same place in your program. There's nothing silly or meaningless about this. When the breakpoints are conditional, this is even useful (see "Break conditions").

GDB itself sometimes sets breakpoints in your program for special purposes, such as proper handling of longjmp (in C programs). These internal breakpoints are assigned negative numbers, starting with -1; info breakpoints doesn't display them.

You can see these breakpoints with the GDB maintenance command, maint info breakpoints.

maint info breakpoints
Using the same format as info breakpoints, display both the breakpoints you've set explicitly and those GDB is using for internal purposes. The type column identifies what kind of breakpoint is shown:
  • breakpoint — normal, explicitly set breakpoint.
  • watchpoint — normal, explicitly set watchpoint.
  • longjmp — internal breakpoint, used to handle correctly stepping through longjmp calls.
  • longjmp resume — internal breakpoint at the target of a longjmp.
  • until — temporary internal breakpoint used by the GDB until command.
  • finish — temporary internal breakpoint used by the GDB finish command.