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 gdb, your program may stop for any of several reasons, such as a signal, a breakpoint, or reaching a new line after a gdb 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 gdb 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, what process it is, 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 (refer to Section 7.1.1 Setting breakpoints), to specify the place where your program should stop by line number, function name or exact address in the program.
In HP-UX, SunOS 4.x, SVR4, and Alpha OSF/1 configurations, you can set breakpoints in shared libraries before the executable is run. There is a minor limitation on HP-UX systems: you must wait until the executable is run in order to set breakpoints in shared library routines that are not called directly by the program (for example, routines that are arguments in a pthread_create call).
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 (refer to Section 7.1.2 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. Refer to Section 10.6 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 (refer to Section 7.1.3 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. Refer to Section 7.3 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 range of breakpoints on which to operate. A breakpoint range is either a single breakpoint number, like 5, or two such numbers, in increasing order, separated by a hyphen, like 5-7. When a breakpoint range is given to a command, all breakpoint in that range are operated on.
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; refer to Section 10.9 Convenience variables, 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. Refer to Section 7.1.8 Breakpoint menus, 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 stack frame. Refer to Section 8.1 Stack frames for a description of stack frames.)
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.
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 (refer to Chapter 8 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, 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 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. Refer to Section 7.1.6 Break conditions 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. Refer to Section 7.1.5 Disabling breakpoints.
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 some 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 gdb will reject this command if more than two are used. Delete or disable unused hardware breakpoints before setting new ones (refer to Section 7.1.5 Disabling breakpoints and Section 7.1.6 Break conditions.
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. Refer to Section 7.1.5 Disabling breakpoints and Section 7.1.6 Break conditions.
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.
Print a table of all breakpoints, watchpoints, and catchpoints set and not deleted, with the following columns for each breakpoint:
Breakpoint, watchpoint, or catchpoint.
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 (refer to Section 10.5 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.
gdb 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 (refer to Section 7.1.6 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 does not display them. You can see these breakpoints with the gdb maintenance command maint info breakpoints (refer to Appendix C Maintenance Commands).
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.
Depending on your system, watchpoints may be implemented in software or hardware. gdb does software watchpointing by single-stepping your program and testing the variable's value each time, which is hundreds of times slower than normal execution. (But this may still be worth it, to catch errors where you have no clue what part of your program is the culprit.)
On some systems, such as HP-UX, gnu/Linux and some other x86-based targets, gdb includes support for hardware watchpoints, which do not slow down the running of your program.
Set a watchpoint for an expression. gdb will break when expr is written into by the program and its value changes.
Set a watchpoint that will break when watch expr is read by the program.
Set a watchpoint that will break when expr is either read or written into by the program.
This command prints a list of watchpoints, breakpoints, and catchpoints; it is the same as info break.
gdb sets a hardware watchpoint if possible. Hardware watchpoints execute very quickly, and the debugger reports a change in value at the exact instruction where the change occurs. If gdb cannot set a hardware watchpoint, it sets a software watchpoint, which executes more slowly and reports the change in value at the next statement, not the instruction, after the change occurs.
When you issue the watch command, gdb reports
Hardware watchpoint num: expr |
if it was able to set a hardware watchpoint.
Currently, the awatch and rwatch commands can only set hardware watchpoints, because accesses to data that don't change the value of the watched expression cannot be detected without examining every instruction as it is being executed, and gdb does not do that currently. If gdb finds that it is unable to set a hardware breakpoint with the awatch or rwatch command, it will print a message like this:
Expression cannot be implemented with read/access watchpoint. |
Sometimes, gdb cannot set a hardware watchpoint because the data type of the watched expression is wider than what a hardware watchpoint on the target machine can handle. For example, some systems can only watch regions that are up to 4 bytes wide; on such systems you cannot set hardware watchpoints for an expression that yields a double-precision floating-point number (which is typically 8 bytes wide). As a work-around, it might be possible to break the large region into a series of smaller ones and watch them with separate watchpoints.
If you set too many hardware watchpoints, gdb might be unable to insert all of them when you resume the execution of your program. Since the precise number of active watchpoints is unknown until such time as the program is about to be resumed, gdb might not be able to warn you about this when you set the watchpoints, and the warning will be printed only when the program is resumed:
Hardware watchpoint num: Could not insert watchpoint |
If this happens, delete or disable some of the watchpoints.
The SPARClite DSU will generate traps when a program accesses some data or instruction address that is assigned to the debug registers. For the data addresses, DSU facilitates the watch command. 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. gdb will reject the command if you try to mix watchpoints. Delete or disable unused watchpoint commands before setting new ones.
If you call a function interactively using print or call, any watchpoints you have set will be inactive until gdb reaches another kind of breakpoint or the call completes.
gdb automatically deletes watchpoints that watch local (automatic) variables, or expressions that involve such variables, when they go out of scope, that is, when the execution leaves the block in which these variables were defined. In particular, when the program being debugged terminates, all local variables go out of scope, and so only watchpoints that watch global variables remain set. If you rerun the program, you will need to set all such watchpoints again. One way of doing that would be to set a code breakpoint at the entry to the main function and when it breaks, set all the watchpoints.
Warning: In multi-thread programs, watchpoints have only limited usefulness. With the current watchpoint implementation, gdb can only watch the value of an expression in a single thread. If you are confident that the expression can only change due to the current thread's activity (and if you are also confident that no other thread can become current), then you can use watchpoints as usual. However, gdb may not notice when a non-current thread's activity changes the expression.
HP-UX Warning: In multi-thread programs, software watchpoints have only limited usefulness. If gdb creates a software watchpoint, it can only watch the value of an expression in a single thread. If you are confident that the expression can only change due to the current thread's activity (and if you are also confident that no other thread can become current), then you can use software watchpoints as usual. However, gdb may not notice when a non-current thread's activity changes the expression. (Hardware watchpoints, in contrast, watch an expression in all threads.)
You can use catchpoints to cause the debugger to stop for certain kinds of program events, such as C++ exceptions or the loading of a shared library. Use the catch command to set a catchpoint.
Stop when event occurs. event can be any of the following:
The throwing of a C++ exception.
The catching of a C++ exception.
A call to exec. This is currently only available for HP-UX.
A call to fork. This is currently only available for HP-UX.
A call to vfork. This is currently only available for HP-UX.
The dynamic loading of any shared library, or the loading of the library libname. This is currently only available for HP-UX.
The unloading of any dynamically loaded shared library, or the unloading of the library libname. This is currently only available for HP-UX.
Set a catchpoint that is enabled only for one stop. The catchpoint is automatically deleted after the first time the event is caught.
Use the info break command to list the current catchpoints.
There are currently some limitations to C++ exception handling (catch throw and catch catch) in gdb:
If you call a function interactively, gdb normally returns control to you when the function has finished executing. If the call raises an exception, however, the call may bypass the mechanism that returns control to you and cause your program either to abort or to simply continue running until it hits a breakpoint, catches a signal that gdb is listening for, or exits. This is the case even if you set a catchpoint for the exception; catchpoints on exceptions are disabled within interactive calls.
You cannot raise an exception interactively.
You cannot install an exception handler interactively.
Sometimes catch is not the best way to debug exception handling: if you need to know exactly where an exception is raised, it is better to stop before the exception handler is called, since that way you can see the stack before any unwinding takes place. If you set a breakpoint in an exception handler instead, it may not be easy to find out where the exception was raised.
To stop just before an exception handler is called, you need some knowledge of the implementation. In the case of gnu C++, exceptions are raised by calling a library function named __raise_exception which has the following ANSI C interface:
/* addr is where the exception identifier is stored.
id is the exception identifier. */
void __raise_exception (void **addr, void *id); |
To make the debugger catch all exceptions before any stack unwinding takes place, set a breakpoint on __raise_exception (refer to Section 7.1 Breakpoints, watchpoints, and catchpoints).
With a conditional breakpoint (refer to Section 7.1.6 Break conditions) that depends on the value of id, you can stop your program when a specific exception is raised. You can use multiple conditional breakpoints to stop your program when any of a number of exceptions are raised.
It is often necessary to eliminate a breakpoint, watchpoint, or catchpoint 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, watchpoints, or catchpoints by specifying their breakpoint numbers.
It is not necessary to delete a breakpoint to proceed past it. gdb 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 (refer to Section 8.3 Selecting a frame). 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, watchpoints, or catchpoints of the breakpoint ranges specified as arguments. If no argument is specified, delete all breakpoints (gdb asks confirmation, unless you have set confirm off). You can abbreviate this command as d.
Rather than deleting a breakpoint, watchpoint, or catchpoint, 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, watchpoints, and catchpoints 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, watchpoints, and catchpoints if you do not know which numbers to use.
A breakpoint, watchpoint, or catchpoint 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.
Enabled for deletion. The breakpoint stops your program, but immediately after it does so it is deleted permanently. A breakpoint set with the tbreak command starts out in this state.
You can use the following commands to enable or disable breakpoints, watchpoints, and catchpoints:
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. gdb disables any of these breakpoints immediately after stopping your program.
Enable the specified breakpoints to work once, then die. gdb deletes any of these breakpoints as soon as your program stops there.
Except for a breakpoint set with tbreak (refer to Section 7.1.1 Setting breakpoints), 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; (refer to Section 7.2 Continuing and stepping.)
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 (refer to Section 10.1 Expressions). 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, gdb 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 than break conditions for the purpose of performing side effects when a breakpoint is reached (refer to Section 7.1.7 Breakpoint command lists).
Break conditions can be specified when a breakpoint is set, by using if in the arguments to the break command. Refer to Section 7.1.1 Setting breakpoints. They can also be changed at any time with the condition command.
You can also use the if keyword with the watch command. The catch command does not recognize the if keyword; condition is the only way to impose a further condition on a catchpoint.
Specify expression as the break condition for breakpoint, watchpoint, or catchpoint 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, gdb checks expression immediately for syntactic correctness, and to determine whether symbols in it have referents in the context of your breakpoint. If expression uses symbols not referenced in the context of the breakpoint, gdb prints an error message:
No symbol "foo" in current context. |
gdb does not actually evaluate expression at the time the condition command (or a command that sets a breakpoint with a condition, like break if …) is given, however. Refer to Section 10.1 Expressions.
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, gdb 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. Refer to Section 7.2 Continuing and stepping.
If a breakpoint has a positive ignore count and a condition, the condition is not checked. Once the ignore count reaches zero, gdb 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. Refer to Section 10.9 Convenience variables.
Ignore counts apply to breakpoints, watchpoints, and catchpoints.
You can give any breakpoint (or watchpoint or catchpoint) 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, watchpoint, or catchpoint set (not to the breakpoint most recently encountered).
Pressing
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. Refer to Section 22.4 Commands for controlled 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++ and Objective-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 gdb 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, gdb 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)
|
Under some operating systems, breakpoints cannot be used in a program if any other process is running that program. In this situation, attempting to run or continue a program with a breakpoint causes gdb to print an error message:
Cannot insert breakpoints. The same program may be running in another process. |
When this happens, you have three ways to proceed:
Remove or disable the breakpoints, then continue.
Suspend gdb, and copy the file containing your program to a new name. Resume gdb and use the exec-file command to specify that gdb should run your program under that name. Then start your program again.
Relink your program so that the text segment is nonsharable, using the linker option -N. The operating system limitation may not apply to nonsharable executables.
A similar message can be printed if you request too many active hardware-assisted breakpoints and watchpoints:
Stopped; cannot insert breakpoints. You may have requested too many hardware breakpoints and watchpoints. |
This message is printed when you attempt to resume the program, since only then gdb knows exactly how many hardware breakpoints and watchpoints it needs to insert.
When this message is printed, you need to disable or remove some of the hardware-assisted breakpoints and watchpoints, and then continue.