Debugging programs with multiple threads

In some operating systems, such as HP-UX, a single program may have more than one thread of execution. The precise semantics of threads differ from one operating system to another, but in general, the threads of a single program are akin to multiple processes - except that they share one address space (that is, they can all examine and modify the same variables). On the other hand, each thread has its own registers and execution stack, and private memory.

GDB provides these facilities for debugging multi-thread programs:

	WARNING! These facilities are not yet available on every GDB configuration where the operating system supports threads. If your GDB does not support threads, these commands have no effect. For example, a system without thread support shows no output from `info threads', and always rejects the thread command, like this: ((gdb)) info threads ((gdb)) thread 1 Thread ID 1 not known. Use the "info threads" command to see the IDs of currently known threads.

The GDB thread debugging facility allows you to observe all threads while your program runs - but whenever GDB takes control, one thread in particular is always the focus of debugging. This thread is called the current thread. Debugging commands show program information from the perspective of the current thread.

Whenever GDB detects a new thread in your program, it displays the target system's identification for the thread with a message in the form [New systag]. systag is a thread identifier whose form varies depending on the particular system.

For debugging purposes, GDB associates its own thread number - always a single integer - with each thread in your program.

Following commands are used to debug multi-threaded programs:

info threads

Display a summary of all threads currently in your program. GDB displays for each thread (in this order) :

An asterisk * to the left of the GDB thread number indicates the current thread.

For example,

((gdb)) info threads
3 process 35 thread 27 0x34e5 in sigpause ()
2 process 35 thread 23 0x34e5 in sigpause ()
* 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8)
at threadtest.c:68

On HP-UX systems:

For debugging purposes, GDB associates its own thread number - a small integer as - signed in thread-creation order - with each thread in your program.

Whenever GDB detects a new thread in your program, it displays both GDB's thread number and the target system's identification for the thread with a message in the form [New systag]- systag is a thread identifier whose form varies depending on the particular system. For example, on HP-UX, you see

[New thread 2 (system thread 26594)]

when GDB notices a new thread.

thread threadno

Make thread number threadno the current thread. The command argument threadno is the internal GDB thread number, as shown in the first field of the info threads display. GDB responds by displaying the system identifier of the thread you selected, and its current stack frame summary:

((gdb)) thread 2
[Switching to thread 2 (system thread 26594)]
0x34e5 in sigpause ()

As with the [New...] message, the form of the text after Switching to depends on your system's conventions for identifying threads.

thread apply [threadno] [all] args

The thread apply command allows you to apply a command to one or more threads. Specify the numbers of the threads that you want affected with the command argument threadno. The threadno is the internal GDB thread number, as shown in the first field of the info threads display. To apply a command to all threads, use thread apply all args.

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 of the form [Switching to systag] to identify the thread.

	NOTE: On HP-UX 11.x, debugging a multi-thread process can cause a deadlock if the process is waiting for an NFS-server response. A thread can be stopped while asleep in this state, and NFS holds a lock on the rnode while asleep.

To prevent the thread from being interrupted while holding the rnodelock, make the NFS mount non-interruptible with the nointr flag. See mount(1).

On HP-UX systems, you can control the display of thread creation messages. Following commands are used to control the display of thread creation:

set threadverbose on

Enable the output of informational messages regarding thread creation. The default setting is on. You can set it to off to stop the display of messages.

set threadverbose off

Disable the output of informational messages regarding thread creation. The default setting is on. You can set it to on to display messages.

show threadverbose

Display whether set threadverbose is on or off.

When your program has 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.

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

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 the action you requested.