Debugging with GDB

Node:Thread Stops, Previous:Signals, Up:Stopping

### Stopping and starting multi-thread programs

When your program has multiple threads (see 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, 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 the breakpoint condition, like this:

                (gdb) break frik.c:13 thread 28 if bartab > lim

Whenever your program stops under GDB for any reason, all threads of execution stop, not just the current thread. This allows you to examine the overall state of the program, including switching between threads, without worrying that things may change underfoot.

Conversely, whenever you restart the program, all threads start executing. This is true even when single-stepping with commands like `step` or `next`.

In particular, GDB cannot single-step all threads in lockstep. Since thread scheduling is up to your debugging target's operating system (not controlled by GDB), other threads may execute more than one statement while the current thread completes a single step. Moreover, in general other threads stop in the middle of a statement, rather than at a clean statement boundary, when the program stops.

You might even find your program stopped in another thread after continuing or even single-stepping. This happens whenever some other thread runs into a breakpoint, a signal, or an exception before the first thread completes whatever you requested.

On some OSes, you can lock the OS scheduler and thus 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 stops other threads from "seizing the prompt" by preempting the current thread while you are stepping. Other threads will 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, they will never steal the GDB prompt away from the thread that you are debugging.
`show scheduler-locking`
  Display the current scheduler locking mode.