| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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
5.1 Breakpoints, Watchpoints, and Catchpoints Breakpoints, watchpoints, and catchpoints 5.2 Continuing and Stepping Resuming execution 5.3 Skipping Over Functions and Files Skipping over functions and files 5.4 Signals 5.5 Stopping and Starting Multi-thread Programs Stopping and starting multi-thread programs
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
On some systems, 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. The expression may be a value of a variable, or it could involve values of one or more variables combined by operators, such as `a + b'. This is sometimes called data breakpoints. You must use a different command to set watchpoints (see 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.
A catchpoint is another special breakpoint that stops your program
when a certain kind of event occurs, such as the throwing of a C++
exception or the loading of a library. As with watchpoints, you use a
different command to set a catchpoint (see section Setting Catchpoints), but aside from that, you can manage a catchpoint like any
other breakpoint. (To stop when your program receives a signal, use the
handle command; see Signals.)
GDB assigns a number to each breakpoint, watchpoint, or catchpoint when you create it; these numbers are successive integers starting with one. In many of the commands for controlling various features of breakpoints you use the breakpoint number to say which breakpoint you want to change. Each breakpoint may be enabled or disabled; if disabled, it has no effect on your program until you enable it again.
Some GDB commands accept a 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 breakpoints in that range are operated on.
5.1.1 Setting Breakpoints Setting breakpoints 5.1.2 Setting Watchpoints Setting watchpoints 5.1.3 Setting Catchpoints Setting catchpoints 5.1.4 Deleting Breakpoints Deleting breakpoints 5.1.5 Disabling Breakpoints Disabling breakpoints 5.1.6 Break Conditions Break conditions 5.1.7 Breakpoint Command Lists Breakpoint command lists 5.1.8 How to save breakpoints to a file How to save breakpoints in a file 5.1.9 "Cannot insert breakpoints" 5.1.10 "Breakpoint address adjusted..."
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
break location
When using source languages that permit overloading of symbols, such as C++, a function name may refer to more than one possible place to break. See section Ambiguous Expressions, for a discussion of that situation.
It is also possible to insert a breakpoint that will stop the program only if a specific thread (see section 5.5.4 Thread-Specific Breakpoints) or a specific task (see section 15.4.8.6 Extensions for Ada Tasks) hits that breakpoint.
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 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
GDB 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 GDB will use, see set remote hardware-breakpoint-limit.
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.
See also Break Conditions.
rbreak regex
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:
(gdb) rbreak . |
rbreak file:regex
rbreak is called with a filename qualification, it limits
the search for functions matching the given regular expression to the
specified file. This can be used, for example, to set breakpoints on
every function in a given file:
(gdb) rbreak file.c:. |
The colon separating the filename qualifier from the regex may optionally be surrounded by spaces.
info breakpoints [n...]
info break [n...]
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.
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).
It is possible that a breakpoint corresponds to several locations in your program. Examples of this situation are:
In all those cases, GDB will insert a breakpoint at all the relevant locations.
A breakpoint with multiple locations is displayed in the breakpoint table using several rows--one header row, followed by one row for each breakpoint location. The header row has `<MULTIPLE>' in the address column. The rows for individual locations contain the actual addresses for locations, and show the functions to which those locations belong. The number column for a location is of the form breakpoint-number.location-number.
For example:
Num Type Disp Enb Address What
1 breakpoint keep y <MULTIPLE>
stop only if i==1
breakpoint already hit 1 time
1.1 y 0x080486a2 in void foo<int>() at t.cc:8
1.2 y 0x080486ca in void foo<double>() at t.cc:8
|
Each location can be individually enabled or disabled by passing
breakpoint-number.location-number as argument to the
enable and disable commands. Note that you cannot
delete the individual locations from the list, you can only delete the
entire list of locations that belong to their parent breakpoint (with
the delete num command, where num is the number of
the parent breakpoint, 1 in the above example). Disabling or enabling
the parent breakpoint (see section 5.1.5 Disabling Breakpoints) affects all of the locations
that belong to that breakpoint.
It's quite common to have a breakpoint inside a shared library. Shared libraries can be loaded and unloaded explicitly, and possibly repeatedly, as the program is executed. To support this use case, GDB updates breakpoint locations whenever any shared library is loaded or unloaded. Typically, you would set a breakpoint in a shared library at the beginning of your debugging session, when the library is not loaded, and when the symbols from the library are not available. When you try to set breakpoint, GDB will ask you if you want to set a so called pending breakpoint---breakpoint whose address is not yet resolved.
After the program is run, whenever a new shared library is loaded, GDB reevaluates all the breakpoints. When a newly loaded shared library contains the symbol or line referred to by some pending breakpoint, that breakpoint is resolved and becomes an ordinary breakpoint. When a library is unloaded, all breakpoints that refer to its symbols or source lines become pending again.
This logic works for breakpoints with multiple locations, too. For example, if you have a breakpoint in a C++ template function, and a newly loaded shared library has an instantiation of that template, a new location is added to the list of locations for the breakpoint.
Except for having unresolved address, pending breakpoints do not differ from regular breakpoints. You can set conditions or commands, enable and disable them and perform other breakpoint operations.
GDB provides some additional commands for controlling what happens when the `break' command cannot resolve breakpoint address specification to an address:
set breakpoint pending auto
set breakpoint pending on
set breakpoint pending off
show breakpoint pending
The settings above only affect the break command and its
variants. Once breakpoint is set, it will be automatically updated
as shared libraries are loaded and unloaded.
For some targets, GDB 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, GDB will always use hardware
breakpoints.
You can control this automatic behaviour with the following commands::
set breakpoint auto-hw on
set breakpoint auto-hw off
GDB normally implements breakpoints by replacing the program code at the breakpoint address with a special instruction, which, when executed, given control to the debugger. By default, the program code is so modified only when the program is resumed. As soon as the program stops, GDB restores the original instructions. This behaviour guards against leaving breakpoints inserted in the target should gdb abrubptly disconnect. However, with slow remote targets, inserting and removing breakpoint can reduce the performance. This behavior can be controlled with the following commands::
set breakpoint always-inserted off
set breakpoint always-inserted on
set breakpoint always-inserted auto
breakpoint always-inserted mode is on. If GDB is
controlling the inferior in all-stop mode, GDB behaves as if
breakpoint always-inserted mode is off.
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' (see maint info breakpoints).
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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. (This is sometimes called a data breakpoint.) The expression may be as simple as the value of a single variable, or as complex as many variables combined by operators. Examples include:
int occupies 4 bytes).
You can set a watchpoint on an expression even if the expression can
not be evaluated yet. For instance, you can set a watchpoint on
`*global_ptr' before `global_ptr' is initialized.
GDB will stop when your program sets `global_ptr' and
the expression produces a valid value. If the expression becomes
valid in some other way than changing a variable (e.g. if the memory
pointed to by `*global_ptr' becomes readable as the result of a
malloc call), GDB may not stop until the next time
the expression changes.
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, PowerPC, GNU/Linux and most other x86-based targets, GDB includes support for hardware watchpoints, which do not slow down the running of your program.
watch [-l|-location] expr [thread threadnum] [mask maskvalue]
(gdb) watch foo |
If the command includes a [thread threadnum]
argument, GDB breaks only when the thread identified by
threadnum changes the value of expr. If any other threads
change the value of expr, GDB will not break. Note
that watchpoints restricted to a single thread in this way only work
with Hardware Watchpoints.
Ordinarily a watchpoint respects the scope of variables in expr
(see below). The -location argument tells GDB to
instead watch the memory referred to by expr. In this case,
GDB will evaluate expr, take the address of the result,
and watch the memory at that address. The type of the result is used
to determine the size of the watched memory. If the expression's
result does not have an address, then GDB will print an
error.
The [mask maskvalue] argument allows creation
of masked watchpoints, if the current architecture supports this
feature (e.g., PowerPC Embedded architecture, see 21.3.7 PowerPC Embedded.) A masked watchpoint specifies a mask in addition
to an address to watch. The mask specifies that some bits of an address
(the bits which are reset in the mask) should be ignored when matching
the address accessed by the inferior against the watchpoint address.
Thus, a masked watchpoint watches many addresses simultaneously--those
addresses whose unmasked bits are identical to the unmasked bits in the
watchpoint address. The mask argument implies -location.
Examples:
(gdb) watch foo mask 0xffff00ff (gdb) watch *0xdeadbeef mask 0xffffff00 |
rwatch [-l|-location] expr [thread threadnum] [mask maskvalue]
awatch [-l|-location] expr [thread threadnum] [mask maskvalue]
info watchpoints [n...]
info break (see section 5.1.1 Setting Breakpoints).
If you watch for a change in a numerically entered address you need to dereference it, as the address itself is just a constant number which will never change. GDB refuses to create a watchpoint that watches a never-changing value:
(gdb) watch 0x600850 Cannot watch constant value 0x600850. (gdb) watch *(int *) 0x600850 Watchpoint 1: *(int *) 6293584 |
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.
You can force GDB to use only software watchpoints with the
set can-use-hw-watchpoints 0 command. With this variable set to
zero, GDB will never try to use hardware watchpoints, even if
the underlying system supports them. (Note that hardware-assisted
watchpoints that were set before setting
can-use-hw-watchpoints to zero will still use the hardware
mechanism of watching expression values.)
set can-use-hw-watchpoints
show can-use-hw-watchpoints
For remote targets, you can restrict the number of hardware watchpoints GDB will use, see set remote hardware-breakpoint-limit.
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.
Watching complex expressions that reference many variables can also exhaust the resources available for hardware-assisted watchpoints. That's because GDB needs to watch every variable in the expression with separately allocated resources.
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.
There is a known problem with watchpoints on Irix systems. Due to hardware limitations, you will get an error if your program attempts to execute a store-conditional (sc) instruction (often used for implementing low-level locks) to a word in a page that also has a watchpoint set. If this happens, you will see a message such as
PR_FAULTED : Incurred a traced hardware fault FLTSCWATCH: Hit a store conditional on a watched page |
In such cases, you must arrange (using breakpoints) to stop the program and remove the watchpoint before executing the faulting code, re-installing it later.
In multi-threaded programs, watchpoints will detect changes to the watched expression from every thread.
Warning: In multi-threaded 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.)
See set remote hardware-watchpoint-limit.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
catch event
throw
catch
exception
catch exception Program_Error),
the debugger will stop only when this specific exception is raised.
Otherwise, the debugger stops execution when any Ada exception is raised.
When inserting an exception catchpoint on a user-defined exception whose
name is identical to one of the exceptions defined by the language, the
fully qualified name must be used as the exception name. Otherwise,
GDB will assume that it should stop on the pre-defined exception
rather than the user-defined one. For instance, assuming an exception
called Constraint_Error is defined in package Pck, then
the command to use to catch such exceptions is catch exception
Pck.Constraint_Error.
exception unhandled
assert
exec
exec. This is currently only available for HP-UX
and GNU/Linux.
syscall
syscall [name | number] ...
name can be any system call name that is valid for the underlying OS. Just what syscalls are valid depends on the OS. On GNU and Unix systems, you can find the full list of valid syscall names on `/usr/include/asm/unistd.h'.
Normally, GDB knows in advance which syscalls are valid for each OS, so you can use the GDB command-line completion facilities (see section command completion) to list the available choices.
You may also specify the system call numerically. A syscall's number is the value passed to the OS's syscall dispatcher to identify the requested service. When you specify the syscall by its name, GDB uses its database of syscalls to convert the name into the corresponding numeric code, but using the number directly may be useful if GDB's database does not have the complete list of syscalls on your system (e.g., because GDB lags behind the OS upgrades).
The example below illustrates how this command works if you don't provide arguments to it:
(gdb) catch syscall Catchpoint 1 (syscall) (gdb) r Starting program: /tmp/catch-syscall Catchpoint 1 (call to syscall 'close'), \ 0xffffe424 in __kernel_vsyscall () (gdb) c Continuing. Catchpoint 1 (returned from syscall 'close'), \ 0xffffe424 in __kernel_vsyscall () (gdb) |
Here is an example of catching a system call by name:
(gdb) catch syscall chroot Catchpoint 1 (syscall 'chroot' [61]) (gdb) r Starting program: /tmp/catch-syscall Catchpoint 1 (call to syscall 'chroot'), \ 0xffffe424 in __kernel_vsyscall () (gdb) c Continuing. Catchpoint 1 (returned from syscall 'chroot'), \ 0xffffe424 in __kernel_vsyscall () (gdb) |
An example of specifying a system call numerically. In the case below, the syscall number has a corresponding entry in the XML file, so GDB finds its name and prints it:
(gdb) catch syscall 252 Catchpoint 1 (syscall(s) 'exit_group') (gdb) r Starting program: /tmp/catch-syscall Catchpoint 1 (call to syscall 'exit_group'), \ 0xffffe424 in __kernel_vsyscall () (gdb) c Continuing. Program exited normally. (gdb) |
However, there can be situations when there is no corresponding name in XML file for that syscall number. In this case, GDB prints a warning message saying that it was not able to find the syscall name, but the catchpoint will be set anyway. See the example below:
(gdb) catch syscall 764 warning: The number '764' does not represent a known syscall. Catchpoint 2 (syscall 764) (gdb) |
If you configure GDB using the `--without-expat' option, it will not be able to display syscall names. Also, if your architecture does not have an XML file describing its system calls, you will not be able to see the syscall names. It is important to notice that these two features are used for accessing the syscall name database. In either case, you will see a warning like this:
(gdb) catch syscall warning: Could not open "syscalls/i386-linux.xml" warning: Could not load the syscall XML file 'syscalls/i386-linux.xml'. GDB will not be able to display syscall names. Catchpoint 1 (syscall) (gdb) |
Of course, the file name will change depending on your architecture and system.
Still using the example above, you can also try to catch a syscall by its number. In this case, you would see something like:
(gdb) catch syscall 252 Catchpoint 1 (syscall(s) 252) |
Again, in this case GDB would not be able to display syscall's names.
fork
fork. This is currently only available for HP-UX
and GNU/Linux.
vfork
vfork. This is currently only available for HP-UX
and GNU/Linux.
tcatch event
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:
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
clear
clear location
clear function
clear filename:function
clear linenum
clear filename:linenum
delete [breakpoints] [range...]
set
confirm off). You can abbreviate this command as d.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 to
print a list of all breakpoints, watchpoints, and catchpoints if you
do not know which numbers to use.
Disabling and enabling a breakpoint that has multiple locations affects all of its locations.
A breakpoint, watchpoint, or catchpoint 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, watchpoints, and catchpoints:
disable [breakpoints] [range...]
disable as dis.
enable [breakpoints] [range...]
enable [breakpoints] once range...
enable [breakpoints] delete range...
tbreak command start out in this state.
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 Continuing and Stepping.)
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 than break conditions 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.
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.
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. 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. 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
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 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.
Ignore counts apply to breakpoints, watchpoints, and catchpoints.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
commands [range...]
... 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 argument, commands refers to the last breakpoint,
watchpoint, or catchpoint set (not to the breakpoint most recently
encountered). If the most recent breakpoints were set with a single
command, then the commands will apply to all the breakpoints
set by that command. This applies to breakpoints set by
rbreak, and also applies when a single break command
creates multiple breakpoints (see section Ambiguous Expressions).
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 |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
To save breakpoint definitions to a file use the save
breakpoints command.
save breakpoints [filename]
source command (see section 23.1.3 Command Files). Note that watchpoints
with expressions involving local variables may fail to be recreated
because it may not be possible to access the context where the
watchpoint is valid anymore. Because the saved breakpoint definitions
are simply a sequence of GDB commands that recreate the
breakpoints, you can edit the file in your favorite editing program,
and remove the breakpoint definitions you're not interested in, or
that can no longer be recreated.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
If you request too many active hardware-assisted breakpoints and watchpoints, you will see this error message:
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Some processor architectures place constraints on the addresses at which breakpoints may be placed. For architectures thus constrained, GDB will attempt to adjust the breakpoint's address to comply with the constraints dictated by the architecture.
One example of such an architecture is the Fujitsu FR-V. The FR-V is a VLIW architecture in which a number of RISC-like instructions may be bundled together for parallel execution. The FR-V architecture constrains the location of a breakpoint instruction within such a bundle to the instruction with the lowest address. GDB honors this constraint by adjusting a breakpoint's address to the first in the bundle.
It is not uncommon for optimized code to have bundles which contain instructions from different source statements, thus it may happen that a breakpoint's address will be adjusted from one source statement to another. Since this adjustment may significantly alter GDB's breakpoint related behavior from what the user expects, a warning is printed when the breakpoint is first set and also when the breakpoint is hit.
A warning like the one below is printed when setting a breakpoint that's been subject to address adjustment:
warning: Breakpoint address adjusted from 0x00010414 to 0x00010410. |
Such warnings are printed both for user settable and GDB's internal breakpoints. If you see one of these warnings, you should verify that a breakpoint set at the adjusted address will have the desired affect. If not, the breakpoint in question may be removed and other breakpoints may be set which will have the desired behavior. E.g., it may be sufficient to place the breakpoint at a later instruction. A conditional breakpoint may also be useful in some cases to prevent the breakpoint from triggering too often.
GDB will also issue a warning when stopping at one of these adjusted breakpoints:
warning: Breakpoint 1 address previously adjusted from 0x00010414 to 0x00010410. |
When this warning is encountered, it may be too late to take remedial action except in cases where the breakpoint is hit earlier or more frequently than expected.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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
it stops 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 (for foreground, as the
debugged program is deemed to be the foreground program) 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 Catchpoints) 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.
Warning: If you use thestepcommand 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.
The step command only stops at the first instruction of a source
line. This prevents the multiple stops that could otherwise occur in
switch statements, for loops, etc. step continues
to stop if a function that has debugging information is called within
the line. In other words, step steps inside any functions
called within the line.
Also, the step command only enters a function if there is line
number information for the function. 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 only stops at the first instruction of a
source line. This prevents multiple stops that could otherwise occur in
switch statements, for loops, etc.
set step-mode
set step-mode on
set step-mode on command causes the step command to
stop at the first instruction of a function which contains no debug line
information rather than stepping over it.
This is useful in cases where you may be interested in inspecting the machine instructions of a function which has no symbolic info and do not want GDB to automatically skip over this function.
set step-mode off
step command to step over any functions which contains no
debug information. This is the default.
show step-mode
finish
fin.
Contrast this with the return command (see section Returning from a Function).
until
u
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
until without an argument. The specified
location is actually reached only if it is in the current frame. This
implies that until can be used to skip over recursive function
invocations. For instance in the code below, if the current location is
line 96, issuing until 99 will execute the program up to
line 99 in the same invocation of factorial, i.e., after the inner
invocations have returned.
94 int factorial (int value)
95 {
96 if (value > 1) {
97 value *= factorial (value - 1);
98 }
99 return (value);
100 }
|
advance location
until, but advance will
not skip over recursive function calls, and the target location doesn't
have to be in the same frame as the current one.
stepi
stepi arg
si
It is often useful to do `display/i $pc' when stepping by machine instructions. This makes GDB automatically display the next instruction to be executed, each time your program stops. See section Automatic Display.
An argument is a repeat count, as in step.
nexti
nexti arg
ni
An argument is a repeat count, as in next.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The program you are debugging may contain some functions which are
uninteresting to debug. The skip comand lets you tell GDB to
skip a function or all functions in a file when stepping.
For example, consider the following C function:
101 int func()
102 {
103 foo(boring());
104 bar(boring());
105 }
|
Suppose you wish to step into the functions foo and bar, but you
are not interested in stepping through boring. If you run step
at line 103, you'll enter boring(), but if you run next, you'll
step over both foo and boring!
One solution is to step into boring and use the finish
command to immediately exit it. But this can become tedious if boring
is called from many places.
A more flexible solution is to execute skip boring. This instructs
GDB never to step into boring. Now when you execute
step at line 103, you'll step over boring and directly into
foo.
You can also instruct GDB to skip all functions in a file, with, for
example, skip file boring.c.
skip [linespec]
skip function [linespec]
If you do not specify linespec, the function you're currently debugging will be skipped.
(If you have a function called file that you want to skip, use
skip function file.)
skip file [filename]
If you do not specify filename, functions whose source lives in the file you're currently debugging will be skipped.
Skips can be listed, deleted, disabled, and enabled, much like breakpoints. These are the commands for managing your list of skips:
info skip [range]
info skip prints the following information about each skip:
info skip will show the function's
address here.
skip delete [range]
skip enable [range]
skip disable [range]
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 character (often Ctrl-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 (they 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 let the non-erroneous signals like
SIGALRM be silently passed to your program
(so as not to interfere with their role in the program's functioning)
but to stop your program immediately whenever an error signal happens.
You can change these settings with the handle command.
info signals
info handle
info signals sig
info handle is an 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
noignore
pass and noignore are synonyms.
nopass
ignore
nopass and ignore are synonyms.
When a signal stops your program, the signal is not visible to the
program 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.
The default is set to nostop, noprint, pass for
non-erroneous signals such as SIGALRM, SIGWINCH and
SIGCHLD, and to stop, print, pass for the
erroneous signals.
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.
On some targets, GDB can inspect extra signal information
associated with the intercepted signal, before it is actually
delivered to the program being debugged. This information is exported
by the convenience variable $_siginfo, and consists of data
that is passed by the kernel to the signal handler at the time of the
receipt of a signal. The data type of the information itself is
target dependent. You can see the data type using the ptype
$_siginfo command. On Unix systems, it typically corresponds to the
standard siginfo_t type, as defined in the `signal.h'
system header.
Here's an example, on a GNU/Linux system, printing the stray referenced address that raised a segmentation fault.
(gdb) continue
Program received signal SIGSEGV, Segmentation fault.
0x0000000000400766 in main ()
69 *(int *)p = 0;
(gdb) ptype $_siginfo
type = struct {
int si_signo;
int si_errno;
int si_code;
union {
int _pad[28];
struct {...} _kill;
struct {...} _timer;
struct {...} _rt;
struct {...} _sigchld;
struct {...} _sigfault;
struct {...} _sigpoll;
} _sifields;
}
(gdb) ptype $_siginfo._sifields._sigfault
type = struct {
void *si_addr;
}
(gdb) p $_siginfo._sifields._sigfault.si_addr
$1 = (void *) 0x7ffff7ff7000
|
Depending on target support, $_siginfo may also be writable.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GDB supports debugging programs with multiple threads (see section Debugging Programs with Multiple Threads). There are two modes of controlling execution of your program within the debugger. In the default mode, referred to as all-stop mode, when any thread in your program stops (for example, at a breakpoint or while being stepped), all other threads in the program are also stopped by GDB. On some targets, GDB also supports non-stop mode, in which other threads can continue to run freely while you examine the stopped thread in the debugger.
5.5.1 All-Stop Mode All threads stop when GDB takes control 5.5.2 Non-Stop Mode Other threads continue to execute 5.5.3 Background Execution Running your program asynchronously 5.5.4 Thread-Specific Breakpoints Controlling breakpoints 5.5.5 Interrupted System Calls GDB may interfere with system calls 5.5.6 Observer Mode GDB does not alter program behavior
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
In all-stop mode, 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.
Whenever GDB stops your program, due to a breakpoint or a signal, it automatically selects the thread where that breakpoint or signal happened. GDB alerts you to the context switch with a message such as `[Switching to Thread n]' to identify the thread.
On some OSes, you can modify GDB's default behavior by locking the OS scheduler to allow only a single thread to run.
set scheduler-locking mode
off, then there is no
locking and any thread may run at any time. If on, then only the
current thread may run when the inferior is resumed. The step
mode optimizes for single-stepping; it prevents other threads
from preempting the current thread while you are stepping, so that
the focus of debugging does not change unexpectedly.
Other threads only rarely (or never) get a chance to run
when you step. They are more likely to run when you `next' over a
function call, and they are completely free to run when you use commands
like `continue', `until', or `finish'. However, unless another
thread hits a breakpoint during its timeslice, GDB does not change
the current thread away from the thread that you are debugging.
show scheduler-locking
By default, when you issue one of the execution commands such as
continue, next or step, GDB allows only
threads of the current inferior to run. For example, if GDB
is attached to two inferiors, each with two threads, the
continue command resumes only the two threads of the current
inferior. This is useful, for example, when you debug a program that
forks and you want to hold the parent stopped (so that, for instance,
it doesn't run to exit), while you debug the child. In other
situations, you may not be interested in inspecting the current state
of any of the processes GDB is attached to, and you may want
to resume them all until some breakpoint is hit. In the latter case,
you can instruct GDB to allow all threads of all the
inferiors to run with the set schedule-multiple command.
set schedule-multiple
on, all threads of
all processes are allowed to run. When off, only the threads
of the current process are resumed. The default is off. The
scheduler-locking mode takes precedence when set to on,
or while you are stepping and set to step.
show schedule-multiple
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
For some multi-threaded targets, GDB supports an optional mode of operation in which you can examine stopped program threads in the debugger while other threads continue to execute freely. This minimizes intrusion when debugging live systems, such as programs where some threads have real-time constraints or must continue to respond to external events. This is referred to as non-stop mode.
In non-stop mode, when a thread stops to report a debugging event,
only that thread is stopped; GDB does not stop other
threads as well, in contrast to the all-stop mode behavior. Additionally,
execution commands such as continue and step apply by default
only to the current thread in non-stop mode, rather than all threads as
in all-stop mode. This allows you to control threads explicitly in
ways that are not possible in all-stop mode -- for example, stepping
one thread while allowing others to run freely, stepping
one thread while holding all others stopped, or stepping several threads
independently and simultaneously.
To enter non-stop mode, use this sequence of commands before you run or attach to your program:
# Enable the async interface. set target-async 1 # If using the CLI, pagination breaks non-stop. set pagination off # Finally, turn it on! set non-stop on |
You can use these commands to manipulate the non-stop mode setting:
set non-stop on
set non-stop off
show non-stop
Note these commands only reflect whether non-stop mode is enabled,
not whether the currently-executing program is being run in non-stop mode.
In particular, the set non-stop preference is only consulted when
GDB starts or connects to the target program, and it is generally
not possible to switch modes once debugging has started. Furthermore,
since not all targets support non-stop mode, even when you have enabled
non-stop mode, GDB may still fall back to all-stop operation by
default.
In non-stop mode, all execution commands apply only to the current thread
by default. That is, continue only continues one thread.
To continue all threads, issue continue -a or c -a.
You can use GDB's background execution commands (see section 5.5.3 Background Execution) to run some threads in the background while you continue to examine or step others from GDB. The MI execution commands (see section 27.12 GDB/MI Program Execution) are always executed asynchronously in non-stop mode.
Suspending execution is done with the interrupt command when
running in the background, or Ctrl-c during foreground execution.
In all-stop mode, this stops the whole process;
but in non-stop mode the interrupt applies only to the current thread.
To stop the whole program, use interrupt -a.
Other execution commands do not currently support the -a option.
In non-stop mode, when a thread stops, GDB doesn't automatically make that thread current, as it does in all-stop mode. This is because the thread stop notifications are asynchronous with respect to GDB's command interpreter, and it would be confusing if GDB unexpectedly changed to a different thread just as you entered a command to operate on the previously current thread.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GDB's execution commands have two variants: the normal foreground (synchronous) behavior, and a background (asynchronous) behavior. In foreground execution, GDB waits for the program to report that some thread has stopped before prompting for another command. In background execution, GDB immediately gives a command prompt so that you can issue other commands while your program runs.
You need to explicitly enable asynchronous mode before you can use background execution commands. You can use these commands to manipulate the asynchronous mode setting:
set target-async on
set target-async off
show target-async
If the target doesn't support async mode, GDB issues an error message if you attempt to use the background execution commands.
To specify background execution, add a & to the command. For example,
the background form of the continue command is continue&, or
just c&. The execution commands that accept background execution
are:
run
attach
step
stepi
next
nexti
continue
finish
until
Background execution is especially useful in conjunction with non-stop
mode for debugging programs with multiple threads; see 5.5.2 Non-Stop Mode.
However, you can also use these commands in the normal all-stop mode with
the restriction that you cannot issue another execution command until the
previous one finishes. Examples of commands that are valid in all-stop
mode while the program is running include help and info break.
You can interrupt your program while it is running in the background by
using the interrupt command.
interrupt
interrupt -a
Suspend execution of the running program. In all-stop mode,
interrupt stops the whole process, but in non-stop mode, it stops
only the current thread. To stop the whole program in non-stop mode,
use interrupt -a.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 ...
Use the qualifier `thread threadno' with a breakpoint command to specify that you only want GDB to stop the program when a particular thread reaches this breakpoint. threadno is one of the numeric thread identifiers assigned by GDB, shown in the first column of the `info threads' display.
If you do not specify `thread threadno' when you set a breakpoint, the breakpoint applies to all threads of your program.
You can use the thread qualifier on conditional breakpoints as
well; in this case, place `thread threadno' before or
after the breakpoint condition, like this:
(gdb) break frik.c:13 thread 28 if bartab > lim |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
There is an unfortunate side effect when using GDB to debug multi-threaded programs. If one thread stops for a breakpoint, or for some other reason, and another thread is blocked in a system call, then the system call may return prematurely. This is a consequence of the interaction between multiple threads and the signals that GDB uses to implement breakpoints and other events that stop execution.
To handle this problem, your program should check the return value of each system call and react appropriately. This is good programming style anyways.
For example, do not write code like this:
sleep (10); |
The call to sleep will return early if a different thread stops
at a breakpoint or for some other reason.
Instead, write this:
int unslept = 10;
while (unslept > 0)
unslept = sleep (unslept);
|
A system call is allowed to return early, so the system is still conforming to its specification. But GDB does cause your multi-threaded program to behave differently than it would without GDB.
Also, GDB uses internal breakpoints in the thread library to monitor certain events such as thread creation and thread destruction. When such an event happens, a system call in another thread may return prematurely, even though your program does not appear to stop.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
If you want to build on non-stop mode and observe program behavior without any chance of disruption by GDB, you can set variables to disable all of the debugger's attempts to modify state, whether by writing memory, inserting breakpoints, etc. These operate at a low level, intercepting operations from all commands.
When all of these are set to off, then GDB is said to
be observer mode. As a convenience, the variable
observer can be set to disable these, plus enable non-stop
mode.
Note that GDB will not prevent you from making nonsensical
combinations of these settings. For instance, if you have enabled
may-insert-breakpoints but disabled may-write-memory,
then breakpoints that work by writing trap instructions into the code
stream will still not be able to be placed.
set observer on
set observer off
on, this disables all the permission variables
below (except for insert-fast-tracepoints), plus enables
non-stop debugging. Setting this to off switches back to
normal debugging, though remaining in non-stop mode.
show observer
set may-write-registers on
set may-write-registers off
print, or the
jump command. It defaults to on.
show may-write-registers
set may-write-memory on
set may-write-memory off
print. It
defaults to on.
show may-write-memory
set may-insert-breakpoints on
set may-insert-breakpoints off
on.
show may-insert-breakpoints
set may-insert-tracepoints on
set may-insert-tracepoints off
may-insert-fast-tracepoints. It defaults to on.
show may-insert-tracepoints
set may-insert-fast-tracepoints on
set may-insert-fast-tracepoints off
may-insert-tracepoints. It defaults to on.
show may-insert-fast-tracepoints
set may-interrupt on
set may-interrupt off
off, the
interrupt command will have no effect, nor will
Ctrl-c. It defaults to on.
show may-interrupt
| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |