gdb.info: Thread Stops

Go backward to Signals
Go up to Stopping
Go to the top op gdb

Stopping and starting multi-thread programs

When your program has multiple threads (*note Debugging programs with
multiple threads: 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.
   There is an unfortunate side effect.  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.
   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.