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.
info program
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 Setting breakpoints), to specify the place where
your program should stop by line number, function name or exact address
in the program.
In languages with exception handling (such as GNU C++), you can also set
breakpoints where an exception is raised (see section Breakpoints and exceptions).
In SunOS 4.x, SVR4, and Alpha OSF/1 configurations, you can now set breakpoints in shared libraries before the executable is run.
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 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 section Automatic display.
GDB 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 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
break +offset
break -offset
break linenum
break filename:linenum
break filename:function
break *address
break
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, 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.
break ... if cond
tbreak args
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
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. DSU will generate traps when a program accesses
some date or instruction address that is assigned to the debug registers.
However the hardware breakpoint registers can only take two data breakpoints,
and GDB will reject this command if more than two are used.
Delete or disable usused hardware breakpoints before setting
new ones. See section Break conditions.
thbreak args
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.
Also See section Break conditions.
rbreak regex
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.
info breakpoints [n]
info break [n]
info watchpoints [n]
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 Examining memory).
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.
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 (see section 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'.
maint info breakpoints
breakpoint
watchpoint
longjmp
longjmp calls.
longjmp resume
longjmp.
until
until command.
finish
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.
watch expr
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.
will reject the command if you try to mix watchpoints.
Delete or disable unused watchpoint commands before setting new ones.
rwatch expr
rwatch
command.
awatch expr
awatch command.
info watchpoints
info break.
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.
Some languages, such as GNU C++, implement exception handling. You can use GDB to examine what caused your program to raise an exception, and to list the exceptions your program is prepared to handle at a given point in time.
catch exceptions
catch command. exceptions is a list of names of exceptions
to catch.
You can use info catch to list active exception handlers.
See section Information about a frame.
There are currently some limitations to exception handling in GDB:
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
(see section Breakpoints, watchpoints, and exceptions).
With a conditional breakpoint (see section 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 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. GDB automatically ignores breakpoints on the first instruction to be executed when you continue execution without changing the execution address.
clear
clear function
clear filename:function
clear linenum
clear filename:linenum
delete [breakpoints] [bnums...]
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:
break command starts out in this state.
tbreak command starts out in
this state.
You can use the following commands to enable or disable breakpoints and watchpoints:
disable [breakpoints] [bnums...]
disable as dis.
enable [breakpoints] [bnums...]
enable [breakpoints] once bnums...
enable [breakpoints] delete bnums...
Except for a breakpoint set with tbreak (see section 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; see section 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 (see section 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 for the purpose of performing side effects when a breakpoint is reached (see section Breakpoint command lists).
Break conditions can be specified when a breakpoint is set, by using
`if' in the arguments to the break command. See section Setting breakpoints. 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.
condition bnum expression
condition, GDB
checks expression immediately for syntactic correctness, and to
determine whether symbols in it have referents in the context of your
breakpoint.
GDB does
not actually evaluate expression at the time the condition
command is given, however. See section Expressions.
condition bnum
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.
ignore bnum count
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 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. See section Convenience variables.
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.
commands [bnum]
... command-list ...
end
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 RET as a means of repeating the last GDB 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 section 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++) 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)
Continuing means resuming program execution until your program
completes normally. In contrast, stepping means executing just
one more "step" of your program, where "step" may mean either one
line of source code, or one machine instruction (depending on what
particular command you use). Either when continuing
or when stepping, your program may stop even sooner, due to
a breakpoint or a signal. (If due to a signal, you may want to use
handle, or use `signal 0' to resume execution.
See section Signals.)
continue [ignore-count]
c [ignore-count]
fg [ignore-count]
ignore (see section Break conditions).
The argument ignore-count is meaningful only when your program
stopped due to a breakpoint. At other times, the argument to
continue is ignored.
The synonyms c and fg are provided purely for convenience,
and have exactly the same behavior as continue.
To resume execution at a different place, you can use return
(see section Returning from a function) to go back to the
calling function; or jump (see section Continuing at a different address) to go to an arbitrary location in your program.
A typical technique for using stepping is to set a breakpoint (see section Breakpoints, watchpoints, and exceptions) at the beginning of the function or the section of your program where a problem is believed to lie, run your program until it stops at that breakpoint, and then step through the suspect area, examining the variables that are interesting, until you see the problem happen.
step
s.
TheWarning: If you use the
stepcommand while control is within a function that was compiled without debugging information, execution proceeds until control reaches a function that does have debugging information. Likewise, it will not step into a function which is compiled without debugging information. To step through functions without debugging information, use thestepicommand, described below.
step command now only stops at the first instruction of a
source line. This prevents the multiple stops that used to occur in
switch statements, for loops, etc. step continues to stop if a
function that has debugging information is called within the line.
Also, the step command now only enters a subroutine if there is line
number information for the subroutine. Otherwise it acts like the
next command. This avoids problems when using cc -gl
on MIPS machines. Previously, step entered subroutines if there
was any debugging information about the routine.
step count
step, but do so count times. If a
breakpoint is reached,
or a signal not related to stepping occurs before count steps,
stepping stops right away.
next [count]
step, but function calls that appear within the line
of code are executed without stopping. Execution stops when control
reaches a different line of code at the original stack level that was
executing when you gave the next command. This command is abbreviated
n.
An argument count is a repeat count, as for step.
The next command now only stops at the first instruction of a
source line. This prevents the multiple stops that used to occur in
swtch statements, for loops, etc.
finish
return command (see section Returning from a function).
u
until
next
command, except that when until encounters a jump, it
automatically continues execution until the program counter is greater
than the address of the jump.
This means that when you reach the end of a loop after single stepping
though it, until makes your program continue execution until it
exits the loop. In contrast, a next command at the end of a loop
simply steps back to the beginning of the loop, which forces you to step
through the next iteration.
until always stops your program if it attempts to exit the current
stack frame.
until may produce somewhat counterintuitive results if the order
of machine code does not match the order of the source lines. For
example, in the following excerpt from a debugging session, the f
(frame) command shows that execution is stopped at line
206; yet when we use until, we get to line 195:
(gdb) f
#0 main (argc=4, argv=0xf7fffae8) at m4.c:206
206 expand_input();
(gdb) until
195 for ( ; argc > 0; NEXTARG) {
This happened because, for execution efficiency, the compiler had
generated code for the loop closure test at the end, rather than the
start, of the loop--even though the test in a C for-loop is
written before the body of the loop. The until command appeared
to step back to the beginning of the loop when it advanced to this
expression; however, it has not really gone to an earlier
statement--not in terms of the actual machine code.
until with no argument works by means of single
instruction stepping, and hence is slower than until with an
argument.
until location
u location
break (see section Setting breakpoints). This form of the command uses breakpoints,
and hence is quicker than until without an argument.
stepi
si
step.
nexti
ni
next.
A signal is an asynchronous event that can happen in a program. The
operating system defines the possible kinds of signals, and gives each
kind a name and a number. For example, in Unix SIGINT is the
signal a program gets when you type an interrupt (often C-c);
SIGSEGV is the signal a program gets from referencing a place in
memory far away from all the areas in use; SIGALRM occurs when
the alarm clock timer goes off (which happens only if your program has
requested an alarm).
Some signals, including SIGALRM, are a normal part of the
functioning of your program. Others, such as SIGSEGV, indicate
errors; these signals are fatal (kill your program immediately) if the
program has not specified in advance some other way to handle the signal.
SIGINT does not indicate an error in your program, but it is normally
fatal so it can carry out the purpose of the interrupt: to kill the program.
GDB has the ability to detect any occurrence of a signal in your program. You can tell GDB in advance what to do for each kind of signal.
Normally, GDB is set up to ignore non-erroneous signals like SIGALRM
(so as not to interfere with their role in the functioning of your program)
but to stop your program immediately whenever an error signal happens.
You can change these settings with the handle command.
info signals
info handle is the new alias for info signals.
handle signal keywords...
The keywords allowed by the handle command can be abbreviated.
Their full names are:
nostop
stop
print keyword as well.
print
noprint
nostop keyword as well.
pass
nopass
When a signal stops your program, the signal is not visible until you
continue. Your program sees the signal then, if pass is in
effect for the signal in question at that time. In other words,
after GDB reports a signal, you can use the handle
command with pass or nopass to control whether your
program sees that signal when you continue.
You can also use the signal command to prevent your program from
seeing a signal, or cause it to see a signal it normally would not see,
or to give it any signal at any time. For example, if your program stopped
due to some sort of memory reference error, you might store correct
values into the erroneous variables and continue, hoping to see more
execution; but your program would probably terminate immediately as
a result of the fatal signal once it saw the signal. To prevent this,
you can continue with `signal 0'. See section Giving your program a signal.
When your program has multiple threads (see section Debugging programs with multiple threads), you can choose whether to set breakpoints on all threads, or on a particular thread.
break linespec thread threadno
break linespec thread threadno if ...
thread qualifier on conditional breakpoints as
well; in this case, place `thread threadno' before the
breakpoint condition, like this:
(gdb) break frik.c:13 thread 28 if bartab > lim
Whenever your program stops under GDB for any reason, all threads of execution stop, not just the current thread. This allows you to examine the overall state of the program, including switching between threads, without worrying that things may change underfoot.
Conversely, whenever you restart the program, all threads start
executing. This is true even when single-stepping with commands
like step or next.
In particular, GDB cannot single-step all threads in lockstep. Since thread scheduling is up to your debugging target's operating system (not controlled by GDB), other threads may execute more than one statement while the current thread completes a single step. Moreover, in general other threads stop in the middle of a statement, rather than at a clean statement boundary, when the program stops.
You might even find your program stopped in another thread after continuing or even single-stepping. This happens whenever some other thread runs into a breakpoint, a signal, or an exception before the first thread completes whatever you requested.
Go to the first, previous, next, last section, table of contents.