The principal purposes of using a debugger are so that you can stop your program before it terminates; or so that, if your program runs into trouble, you can investigate and find out why.
Inside the debugger, your program may stop for any of several reasons, such as a breakpoint, or reaching a new line after a debugger command such as step. You may then examine and change variables, set new breakpoints or remove old ones, and then continue execution. Usually, the messages shown by the debugger provide ample explanation of the status of your program — but you can also explicitly request this information at any time.
Display information about the status of your program: whether it is running or not, and why it stopped.
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 Section 11.1.1.), to specify the place where your program should stop by line number, function name or exact address in the program.
A watchpoint is a special breakpoint that stops your program when the value of an expression changes. You must use a different command to set watchpoints (see Section 11.1.2.), 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 the debugger stops at a breakpoint. See Section 14.6.
The debugger assigns a number to each breakpoint or watchpoint 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.
Breakpoints are set with the break command (abbreviated b). The debugger convenience variable $bpnum records the number of the breakpoints you've set most recently; see Section 14.9, for a discussion of what you can do with convenience variables.
You have several ways to say where the breakpoint should go.
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 11.1.7, for a discussion of that situation.
Set a breakpoint some number of lines forward or back from the position at which execution stopped in the currently selected frame.
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.
Set a breakpoint at line linenum in source file filename.
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.
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.
When called without any arguments, break sets a breakpoint at the next instruction to be executed in the selected stack frame (see Chapter 12: 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, the debugger stops the next time it reaches the current location; this may be useful inside loops.
The debugger 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.
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 11.1.5, for more information on breakpoint conditions.
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 11.1.4.
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. However the hardware breakpoint registers can only take two data breakpoints, and the debugger will reject this command if more than two are used. Delete or disable usused hardware breakpoints before setting new ones. See Section 11.1.5.
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 11.1.4. Also See Section 11.1.5.
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.
When debugging C++ programs, rbreak is useful for setting breakpoints on overloaded functions that are not members of any special classes.
Print a table of all breakpoints and watchpoints set and not deleted, with the following columns for each breakpoint:
Breakpoint or watchpoint.
Whether the breakpoint is marked to be disabled or deleted when hit.
Enabled breakpoints are marked with y. n marks breakpoints that are not enabled.
Where the breakpoint is in your program, as a memory address
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.
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 14.5.).
info break now 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.
The debugger 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 11.1.5.).
The debugger 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 debugger maintenance command maint info breakpoints.
Using the same format as info breakpoints, display both the breakpoints you've set explicitly, and those the debugger is using for internal purposes. Internal breakpoints are shown with negative breakpoint numbers. The type column identifies what kind of breakpoint is shown:
Normal, explicitly set breakpoint.
Normal, explicitly set watchpoint.
Internal breakpoint, used to handle correctly stepping through longjmp calls.
Internal breakpoint at the target of a longjmp.
Temporary internal breakpoint used by the debugger until command.
Temporary internal breakpoint used by the debugger finish command.
You can use a watchpoint to stop execution whenever the value of an expression changes, without having to predict a particular place where this may happen.
Watchpoints currently execute two orders of magnitude more slowly than other breakpoints, but this can be well worth it to catch errors where you have no clue what part of your program is the culprit.
The debugger provides two special watchpoints that work at the full speed of the simulator. These are known as hardware breakpoints and will be used in preference to the much slower soft watchpoints.
Set a watchpoint for an expression. The debugger will break when expr is written into by the program and its value changes. However, the hardware breakpoint registers can only take two data watchpoints, and both watchpoints must be the same kind. For example, you can set two watchpoints with watch commands, two with rwatch commands, or two with awatch commands, but you cannot set one watchpoint with one command and the other with a different command. the debugger will reject the command if you try to mix watchpoints. Delete or disable unused watchpoint commands before setting new ones.
Set a watchpoint that will break when watch args is read by the program. If you use both watchpoints, both must be set with the rwatch command.
Set a watchpoint that will break when args is read and written into by the program. If you use both watchpoints, both must be set with the awatch command.
This command prints a list of watchpoints and breakpoints; it is the same as info break.
It is often necessary to eliminate a breakpoint or watchpoint once it has done its job and you no longer want your program to stop there. This is called deleting the breakpoint. A breakpoint that has been deleted no longer exists; it is forgotten.
With the clear command you can delete breakpoints according to where they are in your program. With the delete command you can delete individual breakpoints or watchpoints by specifying their breakpoint numbers.
It is not necessary to delete a breakpoint to proceed past it. The debugger automatically ignores breakpoints on the first instruction to be executed when you continue execution without changing the execution address.
Delete any breakpoints at the next instruction to be executed in the selected stack frame (see Section 12.3.). When the innermost frame is selected, this is a good way to delete a breakpoint where your program just stopped.
Delete any breakpoints set at entry to the function function.
Delete any breakpoints set at or within the code of the specified line.
Delete the breakpoints or watchpoints of the numbers specified as arguments. If no argument is specified, delete all breakpoints (the debugger asks confirmation, unless you have set confirm off). You can abbreviate this command as d.
Rather than deleting a breakpoint or watchpoint, you might prefer to disable it. This makes the breakpoint inoperative as if it had been deleted, but remembers the information on the breakpoint so that you can enable it again later.
You disable and enable breakpoints and watchpoints with the enable and disable commands, optionally specifying one or more breakpoint numbers as arguments. Use info break or info watch to print a list of breakpoints or watchpoints if you do not know which numbers to use.
A breakpoint or watchpoint can have any of four different states of enablement:
Enabled. The breakpoint stops your program. A breakpoint set with the break command starts out in this state.
Disabled. The breakpoint has no effect on your program.
Enabled once. The breakpoint stops your program, but then becomes disabled. A breakpoint set with the tbreak command starts out in this state.
Enabled for deletion. The breakpoint stops your program, but immediately after it does so it is deleted permanently.
You can use the following commands to enable or disable breakpoints and watchpoints:
Disable the specified breakpoints — or all breakpoints, if none are listed. A disabled breakpoint has no effect but is not forgotten. All options such as ignore-counts, conditions and commands are remembered in case the breakpoint is enabled again later. You may abbreviate disable as dis.
Enable the specified breakpoints (or all defined breakpoints). They become effective once again in stopping your program.
Enable the specified breakpoints temporarily. The debugger disables any of these breakpoints immediately after stopping your program.
Enable the specified breakpoints to work once, then die. The debugger deletes any of these breakpoints as soon as your program stops there.
Except for a breakpoint set with tbreak (see Section 11.1.1.), breakpoints that you set are initially enabled; subsequently, they become disabled or enabled only when you use one of the commands above. (The command until can set and delete a breakpoint of its own, but it does not change the state of your other breakpoints; see Section 11.2.)
The simplest sort of breakpoint breaks every time your program reaches a specified place. You can also specify a condition for a breakpoint. A condition is just a Boolean expression in your programming language (see Chapter 28.). A breakpoint with a condition evaluates the expression each time your program reaches it, and your program stops only if the condition is true.
This is the converse of using assertions for program validation; in that situation, you want to stop when the assertion is violated — that is, when the condition is false. In C, if you want to test an assertion expressed by the condition assert, you should set the condition ! assert on the appropriate breakpoint.
Conditions are also accepted for watchpoints; you may not need them, since a watchpoint is inspecting the value of an expression anyhow — but it might be simpler, say, to just set a watchpoint on a variable name, and specify a condition that tests whether the new value is an interesting one.
Break conditions can have side effects, and may even call functions in your program. This can be useful, for example, to activate functions that log program progress, or to use your own print functions to format special data structures. The effects are completely predictable unless there is another enabled breakpoint at the same address. (In that case, the debugger might see the other breakpoint first and stop your program without checking the condition of this one.) Note that breakpoint commands are usually more convenient and flexible for the purpose of performing side effects when a breakpoint is reached (see Section 11.1.6.).
Break conditions can be specified when a breakpoint is set, by using if in the arguments to the break command. See Section 11.1.1. They can also be changed at any time with the condition command. The watch command does not recognize the if keyword; condition is the only way to impose a further condition on a watchpoint.
Specify expression as the break condition for breakpoint or watchpoint number bnum. After you set a condition, breakpoint bnum stops your program only if the value of expression is true (nonzero, in C). When you use condition, the debugger checks expression immediately for syntactic correctness, and to determine whether symbols in it have referents in the context of your breakpoint. The debugger does not actually evaluate expression at the time the condition command is given, however. See Section 14.1.
Remove the condition from breakpoint number bnum. It becomes an ordinary unconditional breakpoint.
A special case of a breakpoint condition is to stop only when the breakpoint has been reached a certain number of times. This is so useful that there is a special way to do it, using the ignore count of the breakpoint. Every breakpoint has an ignore count, which is an integer. Most of the time, the ignore count is zero, and therefore has no effect. But if your program reaches a breakpoint whose ignore count is positive, then instead of stopping, it just decrements the ignore count by one and continues. As a result, if the ignore count value is n, the breakpoint does not stop the next n times your program reaches it.
Set the ignore count of breakpoint number bnum to count. The next count times the breakpoint is reached, your program's execution does not stop; other than to decrement the ignore count, the debugger takes no action.
To make the breakpoint stop the next time it is reached, specify a count of zero.
When you use continue to resume execution of your program from a breakpoint, you can specify an ignore count directly as an argument to continue, rather than using ignore. See Section 11.2.
If a breakpoint has a positive ignore count and a condition, the condition is not checked. Once the ignore count reaches zero, the debugger resumes checking the condition.
You could achieve the effect of the ignore count with a condition such as $foo-- <= 0 using a debugger convenience variable that is decremented each time. See Section 14.9.
You can give any breakpoint (or watchpoint) a series of commands to execute when your program stops due to that breakpoint. For example, you might want to print the values of certain expressions, or enable other breakpoints.
Specify a list of commands for breakpoint number bnum. The commands themselves appear on the following lines. Type a line containing just end to terminate the commands.
To remove all commands from a breakpoint, type commands and follow it immediately with end; that is, give no commands.
With no bnum argument, commands refers to the last breakpoint or watchpoint set (not to the breakpoint most recently encountered).
Pressing Enter as a means of repeating the last the debugger command is disabled within a command-list.
You can use breakpoint commands to start your program up again. Simply use the continue command, or step, or any other command that resumes execution.
Any other commands in the command list, after a command that resumes execution, are ignored. This is because any time you resume execution (even with a simple next or step), you may encounter another breakpoint — which could have its own command list, leading to ambiguities about which list to execute.
If the first command you specify in a command list is silent, the usual message about stopping at a breakpoint is not printed. This may be desirable for breakpoints that are to print a specific message and then continue. If none of the remaining commands print anything, you see no sign that the breakpoint was reached. silent is meaningful only at the beginning of a breakpoint command list.
The commands echo, output, and printf allow you to print precisely controlled output, and are often useful in silent breakpoints. See Commands for controlled output: Output.
For example, here is how you could use breakpoint commands to print the value of x at entry to foo whenever x is positive.
break foo if x>0 commands silent printf "x is %d\n",x cont end
One application for breakpoint commands is to compensate for one bug so you can test for another. Put a breakpoint just after the erroneous line of code, give it a condition to detect the case in which something erroneous has been done, and give it commands to assign correct values to any variables that need them. End with the continue command so that your program does not stop, and start with the silent command so that no output is produced. Here is an example:
break 403 commands silent set x = y + 4 cont end
Some programming languages (notably C++) permit a single function name to be defined several times, for application in different contexts. This is called overloading. When a function name is overloaded, break function is not enough to tell the debugger where you want a breakpoint. If you realize this is a problem, you can use something like break function(types) to specify which particular version of the function you want. Otherwise, the debugger offers you a menu of numbered choices for different possible breakpoints, and waits for your selection with the prompt >. The first two options are always [0] cancel and [1] all. Typing 1 sets a breakpoint at each definition of function, and typing 0 aborts the break command without setting any new breakpoints.
For example, the following session excerpt shows an attempt to set a breakpoint at the overloaded symbol String::after. We choose three particular definitions of that function name:
(gdb) b String::after [0] cancel [1] all [2] file:String.cc; line number:867 [3] file:String.cc; line number:860 [4] file:String.cc; line number:875 [5] file:String.cc; line number:853 [6] file:String.cc; line number:846 [7] file:String.cc; line number:735 > 2 4 6 Breakpoint 1 at 0xb26c: file String.cc, line 867. Breakpoint 2 at 0xb344: file String.cc, line 875. Breakpoint 3 at 0xafcc: file String.cc, line 846. Multiple breakpoints were set. Use the "delete" command to delete unwanted breakpoints. (gdb)