Debugging with GDB: Stopping

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 5. Stopping and Continuing

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`
  Display information about the status of your program: whether it is running or not, what process it is, and why it stopped.

> 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] | [ ? ]

## 5.1 Breakpoints, Watchpoints, and Catchpoints

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 Dynamic Printf |  | Dynamic printf
> 5.1.9 How to save breakpoints to a file |  | How to save breakpoints in a file
> 5.1.10 Static Probe Points |  | Listing static probe points
> 5.1.11 "Cannot insert breakpoints" |  |
> 5.1.12 "Breakpoint address adjusted..." |  |

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 5.1.1 Setting Breakpoints

Breakpoints are set with the `break` command (abbreviated `b`). The debugger convenience variable ``$bpnum'` records the number of the breakpoint you've set most recently; see Convenience Variables, for a discussion of what you can do with convenience variables.

`break location`
  Set a breakpoint at the given location, which can specify a function name, a line number, or an address of an instruction. (See section 9.2 Specifying a Location, for a list of all the possible ways to specify a location.) The breakpoint will stop your program just before it executes any of the code in the specified 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.9.6 Extensions for Ada Tasks) hits that breakpoint.

`break`
  When called without any arguments, `break` sets a breakpoint at the next instruction to be executed in the selected stack frame (see section Examining the Stack). In any selected frame but the innermost, this makes your program stop as soon as control returns to that frame. This is similar to the effect of a `finish` command in the frame inside the selected frame--except that `finish` does not leave an active breakpoint. If you use `break` without an argument in the innermost frame, 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`
  Set a breakpoint with condition cond; evaluate the expression cond each time the breakpoint is reached, and stop only if the value is nonzero--that is, if cond evaluates as true. ``...'` stands for one of the possible arguments described above (or no argument) specifying where to break. See section Break Conditions, for more information on breakpoint conditions.

`tbreak args`
  Set a breakpoint enabled only for one stop. args are the same as for the `break` command, and the breakpoint is set in the same way, but the breakpoint is automatically deleted after the first time your program stops there. See section Disabling Breakpoints.

`hbreak args`
  Set a hardware-assisted breakpoint. args are the same as for the `break` command and the breakpoint is set in the same way, but the breakpoint requires hardware support and some target hardware may not have this support. The main purpose of this is EPROM/ROM code debugging, so you can set a breakpoint at an instruction without changing the instruction. This can be used with the new trap-generation provided by SPARClite DSU and most x86-based targets. These targets will generate traps when a program accesses some data or instruction address that is assigned to the debug registers. However the hardware breakpoint registers can take a limited number of breakpoints. For example, on the DSU, only two data breakpoints can be set at a time, and 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`
  Set a hardware-assisted breakpoint enabled only for one stop. args are the same as for the `hbreak` command and the breakpoint is set in the same way. However, like the `tbreak` command, the breakpoint is automatically deleted after the first time your program stops there. Also, like the `hbreak` command, the breakpoint requires hardware support and some target hardware may not have this support. See section Disabling Breakpoints. See also Break Conditions.

`rbreak regex`
  Set breakpoints on all functions matching the regular expression regex. This command sets an unconditional breakpoint on all matches, printing a list of all breakpoints it set. Once these breakpoints are set, they are treated just like the breakpoints set with the `break` command. You can delete them, disable them, or make them conditional the same way as any other breakpoint.

  The syntax of the regular expression is the standard one used with tools like ``grep'`. Note that this is different from the syntax used by shells, so for instance `foo*` matches all functions that include an `fo` followed by zero or more `o`s. 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`
  If `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...]`
  Print a table of all breakpoints, watchpoints, and catchpoints set and not deleted. Optional argument n means print information only about the specified breakpoint(s) (or watchpoint(s) or catchpoint(s)). For each breakpoint, following columns are printed:

  Breakpoint Numbers
  Type
    Breakpoint, watchpoint, or catchpoint.
  Disposition
    Whether the breakpoint is marked to be disabled or deleted when hit.
  Enabled or Disabled
    Enabled breakpoints are marked with ``y'`. ``n'` marks breakpoints that are not enabled.
  Address
    Where the breakpoint is in your program, as a memory address. For a pending breakpoint whose address is not yet known, this field will contain ``<PENDING>'`. Such breakpoint won't fire until a shared library that has the symbol or line referred by breakpoint is loaded. See below for details. A breakpoint with several locations will have ``<MULTIPLE>'` in this field--see below for details.
  What
    Where the breakpoint is in the source for your program, as a file and line number. For a pending breakpoint, the original string passed to the breakpoint command will be listed as it cannot be resolved until the appropriate shared library is loaded in the future.

  If a breakpoint is conditional, there are two evaluation modes: "host" and "target". If mode is "host", breakpoint condition evaluation is done by GDB on the host's side. If it is "target", then the condition is evaluated by the target. The `info break` command shows the condition on the line following the affected breakpoint, together with its condition evaluation mode in between parentheses.

  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.

  For a breakpoints with an enable count (xref) greater than 1, `info break` also displays that count.

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:

- Multiple functions in the program may have the same name.

- For a C`++` constructor, the GCC compiler generates several instances of the function body, used in different cases.

- For a C`++` template function, a given line in the function can correspond to any number of instantiations.

- For an inlined function, a given source line can correspond to several places where that function is inlined.

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`
  This is the default behavior. When GDB cannot find the breakpoint location, it queries you whether a pending breakpoint should be created.

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

`set breakpoint pending off`
  This indicates that pending breakpoints are not to be created. Any unrecognized breakpoint location results in an error. This setting does not affect any pending breakpoints previously created.

`show breakpoint pending`
  Show the current behavior setting for creating pending breakpoints.

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`
  This is the default behavior. When GDB sets a breakpoint, it will try to use the target memory map to decide if software or hardware breakpoint must be used.

`set breakpoint auto-hw off`
  This indicates GDB should not automatically select breakpoint type. If the target provides a memory map, GDB will warn when trying to set software breakpoint at a read-only address.

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`
  All breakpoints, including newly added by the user, are inserted in the target only when the target is resumed. All breakpoints are removed from the target when it stops.

`set breakpoint always-inserted on`
  Causes all breakpoints to be inserted in the target at all times. If the user adds a new breakpoint, or changes an existing breakpoint, the breakpoints in the target are updated immediately. A breakpoint is removed from the target only when breakpoint itself is removed.

`set breakpoint always-inserted auto`
  This is the default mode. If GDB is controlling the inferior in non-stop mode (see section 5.5.2 Non-Stop Mode), gdb behaves as if `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 handles conditional breakpoints by evaluating these conditions when a breakpoint breaks. If the condition is true, then the process being debugged stops, otherwise the process is resumed.

If the target supports evaluating conditions on its end, GDB may download the breakpoint, together with its conditions, to it.

This feature can be controlled via the following commands:

`set breakpoint condition-evaluation host`
  This option commands GDB to evaluate the breakpoint conditions on the host's side. Unconditional breakpoints are sent to the target which in turn receives the triggers and reports them back to GDB for condition evaluation. This is the standard evaluation mode.

`set breakpoint condition-evaluation target`
  This option commands GDB to download breakpoint conditions to the target at the moment of their insertion. The target is responsible for evaluating the conditional expression and reporting breakpoint stop events back to GDB whenever the condition is true. Due to limitations of target-side evaluation, some conditions cannot be evaluated there, e.g., conditions that depend on local data that is only known to the host. Examples include conditional expressions involving convenience variables, complex types that cannot be handled by the agent expression parser and expressions that are too long to be sent over to the target, specially when the target is a remote system. In these cases, the conditions will be evaluated by GDB.

`set breakpoint condition-evaluation auto`
  This is the default mode. If the target supports evaluating breakpoint conditions on its end, GDB will download breakpoint conditions to the target (limitations mentioned previously apply). If the target does not support breakpoint condition evaluation, then GDB will fallback to evaluating all these conditions on the host's side.

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] | [ ? ]

### 5.1.2 Setting Watchpoints

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:

- A reference to the value of a single variable.

- An address cast to an appropriate data type. For example, ``*(int *)0x12345678'` will watch a 4-byte region at the specified address (assuming an `int` occupies 4 bytes).

- An arbitrarily complex expression, such as ``a*b + c/d'`. The expression can use any operators valid in the program's native language (see section 15. Using GDB with Different Languages).

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]`
  Set a watchpoint for an expression. GDB will break when the expression expr is written into by the program and its value changes. The simplest (and the most popular) use of this command is to watch the value of a single variable:

      (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.6 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]`
  Set a watchpoint that will break when the value of expr is read by the program.

`awatch [-l|-location] expr [thread threadnum] [mask maskvalue]`
  Set a watchpoint that will break when expr is either read from or written into by the program.

`info watchpoints [n...]`
  This command prints a list of watchpoints, using the same format as `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`
  Set whether or not to use hardware watchpoints.

`show can-use-hw-watchpoints`
  Show the current mode of using hardware 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.

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] | [ ? ]

### 5.1.3 Setting Catchpoints

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`
  Stop when event occurs. event can be any of the following:

  `throw [regexp]`
  `rethrow [regexp]`
  `catch [regexp]`
    The throwing, re-throwing, or catching of a C`++` exception.

    If regexp is given, then only exceptions whose type matches the regular expression will be caught.

    The convenience variable `$_exception` is available at an exception-related catchpoint, on some systems. This holds the exception being thrown.

    There are currently some limitations to C`++` exception handling in GDB:

    - The support for these commands is system-dependent. Currently, only systems using the ``gnu-v3'` C`++` ABI (see section 22.6 Configuring the Current ABI) are supported.

    - The regular expression feature and the `$_exception` convenience variable rely on the presence of some SDT probes in `libstdc++`. If these probes are not present, then these features cannot be used. These probes were first available in the GCC 4.8 release, but whether or not they are available in your GCC also depends on how it was built.

    - The `$_exception` convenience variable is only valid at the instruction at which an exception-related catchpoint is set.

    - When an exception-related catchpoint is hit, GDB stops at a location in the system library which implements runtime exception support for C`++`, usually `libstdc++`. You can use `up` (see section 8.4 Selecting a Frame) to get to your code.

    - If you call a function interactively, GDB normally returns control to you when the function has finished executing. If the call raises an exception, however, the call may bypass the mechanism that returns control to you and cause your program either to abort or to simply continue running until it hits a breakpoint, catches a signal that GDB is listening for, or exits. This is the case even if you set a catchpoint for the exception; catchpoints on exceptions are disabled within interactive calls. See section 17.5 Calling Program Functions, for information on controlling this with `set unwind-on-terminating-exception`.

    - You cannot raise an exception interactively.

    - You cannot install an exception handler interactively.

  `exception`
    An Ada exception being raised. If an exception name is specified at the end of the command (eg `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`
    An exception that was raised but is not handled by the program.

  `assert`
    A failed Ada assertion.

  `exec`
    A call to `exec`. This is currently only available for HP-UX and GNU/Linux.

  `syscall`
  `syscall [name | number] ...`
    A call to or return from a system call, a.k.a. syscall. A syscall is a mechanism for application programs to request a service from the operating system (OS) or one of the OS system services. GDB can catch some or all of the syscalls issued by the debuggee, and show the related information for each syscall. If no argument is specified, calls to and returns from all system calls will be caught.

    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`
    A call to `fork`. This is currently only available for HP-UX and GNU/Linux.

  `vfork`
    A call to `vfork`. This is currently only available for HP-UX and GNU/Linux.

  `load [regexp]`
  `unload [regexp]`
    The loading or unloading of a shared library. If regexp is given, then the catchpoint will stop only if the regular expression matches one of the affected libraries.

  `signal [signal... | ``all'`]`
    The delivery of a signal.

    With no arguments, this catchpoint will catch any signal that is not used internally by GDB, specifically, all signals except ``SIGTRAP'` and ``SIGINT'`.

    With the argument ``all'`, all signals, including those used by GDB, will be caught. This argument cannot be used with other signal names.

    Otherwise, the arguments are a list of signal names as given to `handle` (see section 5.4 Signals). Only signals specified in this list will be caught.

    One reason that `catch signal` can be more useful than `handle` is that you can attach commands and conditions to the catchpoint.

    When a signal is caught by a catchpoint, the signal's `stop` and `print` settings, as specified by `handle`, are ignored. However, whether the signal is still delivered to the inferior depends on the `pass` setting; this can be changed in the catchpoint's commands.

`tcatch event`
  Set a catchpoint that is enabled only for one stop. The catchpoint is automatically deleted after the first time the event is caught.

Use the `info break` command to list the current catchpoints.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 5.1.4 Deleting Breakpoints

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`
  Delete any breakpoints at the next instruction to be executed in the selected stack frame (see section Selecting a Frame). When the innermost frame is selected, this is a good way to delete a breakpoint where your program just stopped.

`clear location`
  Delete any breakpoints set at the specified location. See section 9.2 Specifying a Location, for the various forms of location; the most useful ones are listed below:

  `clear function`
  `clear filename:function`
    Delete any breakpoints set at entry to the named function.

  `clear linenum`
  `clear filename:linenum`
    Delete any breakpoints set at or within the code of the specified linenum of the specified filename.

`delete [breakpoints] [range...]`
  Delete the breakpoints, watchpoints, or catchpoints of the breakpoint ranges specified as arguments. If no argument is specified, delete all breakpoints (GDB asks confirmation, unless you have `set confirm off`). You can abbreviate this command as `d`.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 5.1.5 Disabling Breakpoints

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 several different states of enablement:

- Enabled. The breakpoint stops your program. A breakpoint set with the `break` command starts out in this state.
- Disabled. The breakpoint has no effect on your program.
- Enabled once. The breakpoint stops your program, but then becomes disabled.
- Enabled for a count. The breakpoint stops your program for the next N times, then becomes disabled.
- Enabled for deletion. The breakpoint stops your program, but immediately after it does so it is deleted permanently. A breakpoint set with the `tbreak` command starts out in this state.

You can use the following commands to enable or disable breakpoints, watchpoints, and catchpoints:

`disable [breakpoints] [range...]`
  Disable the specified breakpoints--or all breakpoints, if none are listed. A disabled breakpoint has no effect but is not forgotten. All options such as ignore-counts, conditions and commands are remembered in case the breakpoint is enabled again later. You may abbreviate `disable` as `dis`.

`enable [breakpoints] [range...]`
  Enable the specified breakpoints (or all defined breakpoints). They become effective once again in stopping your program.

`enable [breakpoints] once range...`
  Enable the specified breakpoints temporarily. GDB disables any of these breakpoints immediately after stopping your program.

`enable [breakpoints] count count range...`
  Enable the specified breakpoints temporarily. GDB records count with each of the specified breakpoints, and decrements a breakpoint's count when it is hit. When any count reaches 0, GDB disables that breakpoint. If a breakpoint has an ignore count (see section Break Conditions), that will be decremented to 0 before count is affected.

`enable [breakpoints] delete range...`
  Enable the specified breakpoints to work once, then die. GDB deletes any of these breakpoints as soon as your program stops there. Breakpoints set by the `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] | [ ? ]

### 5.1.6 Break Conditions

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

Breakpoint conditions can also be evaluated on the target's side if the target supports it. Instead of evaluating the conditions locally, GDB encodes the expression into an agent expression (see section F. The GDB Agent Expression Mechanism) suitable for execution on the target, independently of GDB. Global variables become raw memory locations, locals become stack accesses, and so forth.

In this case, GDB will only be notified of a breakpoint trigger when its condition evaluates to true. This mechanism may provide faster response times depending on the performance characteristics of the target since it does not need to keep GDB informed about every breakpoint trigger, even those with false conditions.

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`
  Specify expression as the break condition for breakpoint, watchpoint, or catchpoint number bnum. After you set a condition, breakpoint bnum stops your program only if the value of expression is true (nonzero, in C). When you use `condition`, GDB checks expression immediately for syntactic correctness, and to determine whether symbols in it have referents in the context of your breakpoint. If expression uses symbols not referenced in the context of the breakpoint, GDB prints an error message:

      No symbol "foo" in current context.

  GDB does not actually evaluate expression at the time the `condition` command (or a command that sets a breakpoint with a condition, like `break if ...`) is given, however. See section Expressions.

`condition bnum`
  Remove the condition from breakpoint number bnum. It becomes an ordinary unconditional breakpoint.

A special case of a breakpoint condition is to stop only when the breakpoint has been reached a certain number of times. This is so useful that there is a special way to do it, using the ignore count of the breakpoint. Every breakpoint has an ignore count, which is an integer. Most of the time, the ignore count is zero, and therefore has no effect. But if your program reaches a breakpoint whose ignore count is positive, then instead of stopping, it just decrements the ignore count by one and continues. As a result, if the ignore count value is n, the breakpoint does not stop the next n times your program reaches it.

`ignore bnum count`
  Set the ignore count of breakpoint number bnum to count. The next count times the breakpoint is reached, your program's execution does not stop; other than to decrement the ignore count, GDB takes no action.

  To make the breakpoint stop the next time it is reached, specify a count of zero.

  When you use `continue` to resume execution of your program from a breakpoint, you can specify an ignore count directly as an argument to `continue`, rather than using `ignore`. 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] | [ ? ]

### 5.1.7 Breakpoint Command Lists

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`
  Specify a list of commands for the given breakpoints. The commands themselves appear on the following lines. Type a line containing just `end` to terminate the commands.

  To remove all commands from a breakpoint, type `commands` and follow it immediately with `end`; that is, give no commands.

  With no 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] | [ ? ]

### 5.1.8 Dynamic Printf

The dynamic printf command `dprintf` combines a breakpoint with formatted printing of your program's data to give you the effect of inserting `printf` calls into your program on-the-fly, without having to recompile it.

In its most basic form, the output goes to the GDB console. However, you can set the variable `dprintf-style` for alternate handling. For instance, you can ask to format the output by calling your program's `printf` function. This has the advantage that the characters go to the program's output device, so they can recorded in redirects to files and so forth.

If you are doing remote debugging with a stub or agent, you can also ask to have the printf handled by the remote agent. In addition to ensuring that the output goes to the remote program's device along with any other output the program might produce, you can also ask that the dprintf remain active even after disconnecting from the remote target. Using the stub/agent is also more efficient, as it can do everything without needing to communicate with GDB.

`dprintf location,template,expression[,expression...]`
  Whenever execution reaches location, print the values of one or more expressions under the control of the string template. To print several values, separate them with commas.

`set dprintf-style style`
  Set the dprintf output to be handled in one of several different styles enumerated below. A change of style affects all existing dynamic printfs immediately. (If you need individual control over the print commands, simply define normal breakpoints with explicitly-supplied command lists.)

`gdb`
  Handle the output using the GDB `printf` command.

`call`
  Handle the output by calling a function in your program (normally `printf`).

`agent`
  Have the remote debugging agent (such as `gdbserver`) handle the output itself. This style is only available for agents that support running commands on the target.

`set dprintf-function function`
  Set the function to call if the dprintf style is `call`. By default its value is `printf`. You may set it to any expression. that GDB can evaluate to a function, as per the `call` command.

`set dprintf-channel channel`
  Set a "channel" for dprintf. If set to a non-empty value, GDB will evaluate it as an expression and pass the result as a first argument to the `dprintf-function`, in the manner of `fprintf` and similar functions. Otherwise, the dprintf format string will be the first argument, in the manner of `printf`.

  As an example, if you wanted `dprintf` output to go to a logfile that is a standard I/O stream assigned to the variable `mylog`, you could do the following:

      (gdb) set dprintf-style call
      (gdb) set dprintf-function fprintf
      (gdb) set dprintf-channel mylog
      (gdb) dprintf 25,"at line 25, glob=%d\n",glob
      Dprintf 1 at 0x123456: file main.c, line 25.
      (gdb) info break
      1       dprintf        keep y   0x00123456 in main at main.c:25
              call (void) fprintf (mylog,"at line 25, glob=%d\n",glob)
              continue
      (gdb)

  Note that the `info break` displays the dynamic printf commands as normal breakpoint commands; you can thus easily see the effect of the variable settings.

`set disconnected-dprintf on`
`set disconnected-dprintf off`
  Choose whether `dprintf` commands should continue to run if GDB has disconnected from the target. This only applies if the `dprintf-style` is `agent`.

`show disconnected-dprintf off`
  Show the current choice for disconnected `dprintf`.

GDB does not check the validity of function and channel, relying on you to supply values that are meaningful for the contexts in which they are being used. For instance, the function and channel may be the values of local variables, but if that is the case, then all enabled dynamic prints must be at locations within the scope of those locals. If evaluation fails, GDB will report an error.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 5.1.9 How to save breakpoints to a file

To save breakpoint definitions to a file use the `save breakpoints` command.

`save breakpoints [filename]`
  This command saves all current breakpoint definitions together with their commands and ignore counts, into a file ``filename'` suitable for use in a later debugging session. This includes all types of breakpoints (breakpoints, watchpoints, catchpoints, tracepoints). To read the saved breakpoint definitions, use the `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] | [ ? ]

### 5.1.10 Static Probe Points

GDB supports SDT probes in the code. SDT stands for Statically Defined Tracing, and the probes are designed to have a tiny runtime code and data footprint, and no dynamic relocations. They are usable from assembly, C and C`++` languages. See http://sourceware.org/systemtap/wiki/UserSpaceProbeImplementation for a good reference on how the SDT probes are implemented.

Currently, `SystemTap` (http://sourceware.org/systemtap/) SDT probes are supported on ELF-compatible systems. See http://sourceware.org/systemtap/wiki/AddingUserSpaceProbingToApps for more information on how to add `SystemTap` SDT probes in your applications.

Some probes have an associated semaphore variable; for instance, this happens automatically if you defined your probe using a DTrace-style ``.d'` file. If your probe has a semaphore, GDB will automatically enable it when you specify a breakpoint using the ``-probe-stap'` notation. But, if you put a breakpoint at a probe's location by some other method (e.g., `break file:line`), then GDB will not automatically set the semaphore.

You can examine the available static static probes using `info probes`, with optional arguments:

`info probes stap [provider [name [objfile]]]`
  If given, provider is a regular expression used to match against provider names when selecting which probes to list. If omitted, probes by all probes from all providers are listed.

  If given, name is a regular expression to match against probe names when selecting which probes to list. If omitted, probe names are not considered when deciding whether to display them.

  If given, objfile is a regular expression used to select which object files (executable or shared libraries) to examine. If not given, all object files are considered.

`info probes all`
  List the available static probes, from all types.

A probe may specify up to twelve arguments. These are available at the point at which the probe is defined--that is, when the current PC is at the probe's location. The arguments are available using the convenience variables (see section 10.11 Convenience Variables) `$_probe_arg0`...`$_probe_arg11`. Each probe argument is an integer of the appropriate size; types are not preserved. The convenience variable `$_probe_argc` holds the number of arguments at the current probe point.

These variables are always available, but attempts to access them at any location other than a probe point will cause GDB to give an error message.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 5.1.11 "Cannot insert breakpoints"

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] | [ ? ]

### 5.1.12 "Breakpoint address adjusted..."

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] | [ ? ]

## 5.2 Continuing and Stepping

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]`
  Resume program execution, at the address where your program last stopped; any breakpoints set at that address are bypassed. The optional argument ignore-count allows you to specify a further number of times to ignore a breakpoint at this location; its effect is like that of `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`
  Continue running your program until control reaches a different source line, then stop it and return control to GDB. This command is abbreviated `s`.

  > Warning: If you use the `step` command 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 the `stepi` command, 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`
  Continue running as in `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]`
  Continue to the next source line in the current (innermost) stack frame. This is similar to `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`
  The `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`
  Causes the `step` command to step over any functions which contains no debug information. This is the default.

`show step-mode`
  Show whether GDB will stop in or step over functions without source line debug information.

`finish`
  Continue running until just after function in the selected stack frame returns. Print the returned value (if any). This command can be abbreviated as `fin`.

  Contrast this with the `return` command (see section Returning from a Function).

`until`
`u`
  Continue running until a source line past the current line, in the current stack frame, is reached. This command is used to avoid single stepping through a loop more than once. It is like the `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`
  Continue running your program until either the specified location is reached, or the current stack frame returns. location is any of the forms described in 9.2 Specifying a Location. This form of the command uses temporary breakpoints, and hence is quicker than `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`
  Continue running the program up to the given location. An argument is required, which should be of one of the forms described in 9.2 Specifying a Location. Execution will also stop upon exit from the current stack frame. This command is similar to `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`
  Execute one machine instruction, then stop and return to the debugger.

  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`
  Execute one machine instruction, but if it is a function call, proceed until the function returns.

  An argument is a repeat count, as in `next`.

By default, and if available, GDB makes use of target-assisted range stepping. In other words, whenever you use a stepping command (e.g., `step`, `next`), GDB tells the target to step the corresponding range of instruction addresses instead of issuing multiple single-steps. This speeds up line stepping, particularly for remote targets. Ideally, there should be no reason you would want to turn range stepping off. However, it's possible that a bug in the debug info, a bug in the remote stub (for remote targets), or even a bug in GDB could make line stepping behave incorrectly when target-assisted range stepping is enabled. You can use the following command to turn off range stepping if necessary:

`set range-stepping`
`show range-stepping`
  Control whether range stepping is enabled.

  If `on`, and the target supports it, GDB tells the target to step a range of addresses itself, instead of issuing multiple single-steps. If `off`, GDB always issues single-steps, even if range stepping is supported by the target. The default is `on`.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 5.3 Skipping Over Functions and Files

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]`
  After running this command, the function named by linespec or the function containing the line named by linespec will be skipped over when stepping. See section 9.2 Specifying a Location.

  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]`
  After running this command, any function whose source lives in filename will be skipped over when stepping.

  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]`
  Print details about the specified skip(s). If range is not specified, print a table with details about all functions and files marked for skipping. `info skip` prints the following information about each skip:

  Identifier
    A number identifying this skip.
  Type
    The type of this skip, either ``function'` or ``file'`.
  Enabled or Disabled
    Enabled skips are marked with ``y'`. Disabled skips are marked with ``n'`.
  Address
    For function skips, this column indicates the address in memory of the function being skipped. If you've set a function skip on a function which has not yet been loaded, this field will contain ``<PENDING>'`. Once a shared library which has the function is loaded, `info skip` will show the function's address here.
  What
    For file skips, this field contains the filename being skipped. For functions skips, this field contains the function name and its line number in the file where it is defined.

`skip delete [range]`
  Delete the specified skip(s). If range is not specified, delete all skips.

`skip enable [range]`
  Enable the specified skip(s). If range is not specified, enable all skips.

`skip disable [range]`
  Disable the specified skip(s). If range is not specified, disable all skips.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 5.4 Signals

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`
  Print a table of all the kinds of signals and how GDB has been told to handle each one. You can use this to see the signal numbers of all the defined types of signals.

`info signals sig`
  Similar, but print information only about the specified signal number.

  `info handle` is an alias for `info signals`.

`catch signal [signal... | ``all'`]`
  Set a catchpoint for the indicated signals. See section 5.1.3 Setting Catchpoints, for details about this command.

`handle signal [keywords...]`
  Change the way GDB handles signal signal. signal can be the number of a signal or its name (with or without the ``SIG'` at the beginning); a list of signal numbers of the form ``low-high'`; or the word ``all'`, meaning all the known signals. Optional arguments keywords, described below, say what change to make.

The keywords allowed by the `handle` command can be abbreviated. Their full names are:

`nostop`
  GDB should not stop your program when this signal happens. It may still print a message telling you that the signal has come in.

`stop`
  GDB should stop your program when this signal happens. This implies the `print` keyword as well.

`print`
  GDB should print a message when this signal happens.

`noprint`
  GDB should not mention the occurrence of the signal at all. This implies the `nostop` keyword as well.

`pass`
`noignore`
  GDB should allow your program to see this signal; your program can handle the signal, or else it may terminate if the signal is fatal and not handled. `pass` and `noignore` are synonyms.

`nopass`
`ignore`
  GDB should not allow your program to see this signal. `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] | [ ? ]

## 5.5 Stopping and Starting Multi-thread Programs

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] | [ ? ]

### 5.5.1 All-Stop Mode

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`
  Set the scheduler locking mode. If it is `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`
  Display the current scheduler locking mode.

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`
  Set the mode for allowing threads of multiple processes to be resumed when an execution command is issued. When `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`
  Display the current mode for resuming the execution of threads of multiple processes.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 5.5.2 Non-Stop Mode

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`
  Enable selection of non-stop mode.
`set non-stop off`
  Disable selection of non-stop mode.
`show non-stop`
  Show the current non-stop enablement setting.

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.13 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] | [ ? ]

### 5.5.3 Background Execution

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`
  Enable asynchronous mode.
`set target-async off`
  Disable asynchronous mode.
`show target-async`
  Show the current target-async setting.

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`
  See section Starting your Program.

`attach`
  See section Debugging an Already-running Process.

`step`
  See section step.

`stepi`
  See section stepi.

`next`
  See section next.

`nexti`
  See section nexti.

`continue`
  See section continue.

`finish`
  See section finish.

`until`
  See section 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] | [ ? ]

### 5.5.4 Thread-Specific Breakpoints

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 ...`
  linespec specifies source lines; there are several ways of writing them (see section 9.2 Specifying a Location), but the effect is always to specify some source line.

  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

Thread-specific breakpoints are automatically deleted when GDB detects the corresponding thread is no longer in the thread list. For example:

    (gdb) c
    Thread-specific breakpoint 3 deleted - thread 28 no longer in the thread list.

There are several ways for a thread to disappear, such as a regular thread exit, but also when you detach from the process with the `detach` command (see section Debugging an Already-running Process), or if GDB loses the remote connection (see section 20. Debugging Remote Programs), etc. Note that with some targets, GDB is only able to detect a thread has exited when the user explictly asks for the thread list with the `info threads` command.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 5.5.5 Interrupted System Calls

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] | [ ? ]

### 5.5.6 Observer Mode

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`
  When set to `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`
  Show whether observer mode is on or off.

`set may-write-registers on`
`set may-write-registers off`
  This controls whether GDB will attempt to alter the values of registers, such as with assignment expressions in `print`, or the `jump` command. It defaults to `on`.

`show may-write-registers`
  Show the current permission to write registers.

`set may-write-memory on`
`set may-write-memory off`
  This controls whether GDB will attempt to alter the contents of memory, such as with assignment expressions in `print`. It defaults to `on`.

`show may-write-memory`
  Show the current permission to write memory.

`set may-insert-breakpoints on`
`set may-insert-breakpoints off`
  This controls whether GDB will attempt to insert breakpoints. This affects all breakpoints, including internal breakpoints defined by GDB. It defaults to `on`.

`show may-insert-breakpoints`
  Show the current permission to insert breakpoints.

`set may-insert-tracepoints on`
`set may-insert-tracepoints off`
  This controls whether GDB will attempt to insert (regular) tracepoints at the beginning of a tracing experiment. It affects only non-fast tracepoints, fast tracepoints being under the control of `may-insert-fast-tracepoints`. It defaults to `on`.

`show may-insert-tracepoints`
  Show the current permission to insert tracepoints.

`set may-insert-fast-tracepoints on`
`set may-insert-fast-tracepoints off`
  This controls whether GDB will attempt to insert fast tracepoints at the beginning of a tracing experiment. It affects only fast tracepoints, regular (non-fast) tracepoints being under the control of `may-insert-tracepoints`. It defaults to `on`.

`show may-insert-fast-tracepoints`
  Show the current permission to insert fast tracepoints.

`set may-interrupt on`
`set may-interrupt off`
  This controls whether GDB will attempt to interrupt or stop program execution. When this variable is `off`, the `interrupt` command will have no effect, nor will `Ctrl-c`. It defaults to `on`.

`show may-interrupt`
  Show the current permission to interrupt or stop the program.

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by GNAT Mailserver on April, 17 2014 using texi2html