5.1 Breakpoints, Watchpoints, and Catchpoints

A breakpoint 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 break command and its variants (see Setting Breakpoints), to specify the place where your program should stop by line number, function name or exact address in the program.

On some systems, you can set breakpoints in shared libraries before the executable is run.

GDB supports source-tracking breakpoints, which automatically adjust their location when source code changes between recompilations. When enabled with set breakpoint source-tracking enabled on, breakpoints set by file and line number capture a small window of surrounding source lines centered on the breakpoint line. If the source file is modified and the executable is rebuilt, GDB searches a window of approximately 12 lines centered on the breakpoint’s original position for the best match. For each candidate line that matches the original breakpoint line, GDB compares all captured context lines at their corresponding offsets and scores the match by how many lines agree. The candidate with the highest score is selected, provided a majority of the context lines match, reducing false positives from short or repeated lines. If no match meets the threshold, GDB issues a warning and keeps the breakpoint at its original location, disabling source tracking for that breakpoint. Note that breakpoints set by function name or address are not affected by source tracking. Source tracking requires that source files be accessible and that the executable contain line-number debug information.

See Set Breaks.

A watchpoint 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 ‘a + b’. This is sometimes called data breakpoints. You must use a different command to set watchpoints (see Setting Watchpoints), 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.

You can arrange to have values from your program displayed automatically whenever GDB stops at a breakpoint. See Automatic Display.

A catchpoint is another special breakpoint that stops your program when a certain kind of event occurs, such as the throwing of a C++ exception or the loading of a library. As with watchpoints, you use a different command to set a catchpoint (see Setting Catchpoints), but aside from that, you can manage a catchpoint like any other breakpoint. (To stop when your program receives a signal, use the handle command; see Signals.)

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 enabled or disabled; if disabled, it has no effect on your program until you enable it again.

Some GDB commands accept a space-separated list of breakpoints on which to operate. A list element can be either a single breakpoint number, like ‘5’, or a range of such numbers, like ‘5-7’. When a breakpoint list is given to a command, all breakpoints in that list are operated on.