5.1.1 Setting Breakpoints

Breakpoints are set with the break command (abbreviated b). The debugger convenience variable ‘$bpnum’ records the number of the breakpoint 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 function. When using source languages that permit overloading of symbols, such as C++, function may refer to more than one possible place to break. See section Breakpoint Menus, for a discussion of that situation.

break +offset

break -offset

Set a breakpoint some number of lines forward or back from the position at which execution stopped in the currently selected stack frame. (See section Frames, for a description of stack frames.)

break linenum

Set a breakpoint at line linenum in the current source file. The current source file is the last file whose source text was printed. The breakpoint will stop 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 function found in file filename. Specifying a file name 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 which do not have debugging information or source files.

break

When called without any arguments, break sets a breakpoint at the next instruction to be executed in the selected stack frame (see section 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 does not leave an active breakpoint. If you use break without an argument in the innermost frame, No value for GDBN stops the next time it reaches the current location; this may be useful inside loops.

No value for GDBN 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.

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. ‘…’ stands for one of the possible arguments described above (or no argument) specifying where to break. See section Break Conditions, for more information on breakpoint conditions.

tbreak args

Set a breakpoint enabled only for one stop. args are the same as for the break 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 Disabling Breakpoints.

hbreak args

Set a hardware-assisted breakpoint. args are the same as for the break 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 No value for GDBN will reject this command if more than two are used. Delete or disable unused hardware breakpoints before setting new ones (see section Disabling Breakpoints). See section Break Conditions. For remote targets, you can restrict the number of hardware breakpoints No value for GDBN will use, see set remote hardware-breakpoint-limit.

thbreak args

Set a hardware-assisted breakpoint enabled only for one stop. args are the same as for the hbreak command and the breakpoint is set in the same way. 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 and some target hardware may not have this support. See section Disabling Breakpoints. See also 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 are 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.

The syntax of the regular expression is the standard one used with tools like ‘grep’. Note that this is different from the syntax used by shells, so for instance foo* matches all functions that include an fo followed by zero or more os. There is an implicit .* leading and trailing the regular expression you supply, so to match only functions that begin with foo, use ^foo.

When debugging C++ programs, rbreak is useful for setting breakpoints on overloaded functions that are not members of any special classes.

The rbreak command can be used to set breakpoints in all the functions in a program, like this:

(No value for GDBP) rbreak .

info breakpoints [n]

info break [n]

info watchpoints [n]

Print a table of all breakpoints, watchpoints, and catchpoints set and not deleted. Optional argument n means print information only about the specified breakpoint (or watchpoint or catchpoint). For each breakpoint, following columns are printed:

Breakpoint Numbers

Type

Breakpoint, watchpoint, or catchpoint.

Disposition

Whether the breakpoint is marked to be disabled or deleted when hit.

Enabled or Disabled

Enabled breakpoints are marked with ‘y’. ‘n’ marks breakpoints that are not enabled.

Address

Where the breakpoint is in your program, as a memory address. If the breakpoint is pending (see below for details) on a future load of a shared library, the address will be listed as ‘<PENDING>’.

What

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.

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. 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.

info break 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 section Examining Memory).

info break displays a count of 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 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.

No value for GDBN 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 Break Conditions).

If a specified breakpoint location cannot be found, it may be due to the fact that the location is in a shared library that is yet to be loaded. In such a case, you may want No value for GDBN to create a special breakpoint (known as a pending breakpoint) that attempts to resolve itself in the future when an appropriate shared library gets loaded.

Pending breakpoints are useful to set at the start of your No value for GDBN session for locations that you know will be dynamically loaded later by the program being debugged. When shared libraries are loaded, a check is made to see if the load resolves any pending breakpoint locations. If a pending breakpoint location gets resolved, a regular breakpoint is created and the original pending breakpoint is removed.

No value for GDBN provides some additional commands for controlling pending breakpoint support:

set breakpoint pending auto

This is the default behavior. When No value for GDBN cannot find the breakpoint location, it queries you whether a pending breakpoint should be created.

set breakpoint pending on

This indicates that an unrecognized breakpoint location should automatically result in a pending breakpoint being created.

set breakpoint pending off

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.

show breakpoint pending

Show the current behavior setting for creating pending breakpoints.

Normal breakpoint operations apply to pending breakpoints as well. You may specify a condition for a pending breakpoint and/or commands to run when the breakpoint is reached. You can also enable or disable the pending breakpoint. When you specify a condition for a pending breakpoint, the parsing of the condition will be deferred until the point where the pending breakpoint location is resolved. Disabling a pending breakpoint tells No value for GDBN to not attempt to resolve the breakpoint on any subsequent shared library load. When a pending breakpoint is re-enabled, No value for GDBN checks to see if the location is already resolved. This is done because any number of shared library loads could have occurred since the time the breakpoint was disabled and one or more of these loads could resolve the location.

For some targets, No value for GDBN 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 break command as well as to internal breakpoints set by commands like next and finish. For breakpoints set with hbreak, No value for GDBN will always use hardware breakpoints.

You can control this automatic behaviour with the following commands::

set breakpoint auto-hw on

This is the default behavior. When No value for GDBN sets a breakpoint, it will try to use the target memory map to decide if software or hardware breakpoint must be used.

set breakpoint auto-hw off

This indicates No value for GDBN should not automatically select breakpoint type. If the target provides a memory map, No value for GDBN will warn when trying to set software breakpoint at a read-only address.

No value for GDBN 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’ does not display them. You can see these breakpoints with the No value for GDBN maintenance command ‘maint info breakpoints’ (see maint info breakpoints).