4.9 Debugging Programs with Multiple Threads

In some operating systems, such as HP-UX and Solaris, 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 perhaps private memory.

No value for GDBN provides these facilities for debugging multi-thread programs:

• automatic notification of new threads
• ‘thread threadno’, a command to switch among threads
• ‘info threads’, a command to inquire about existing threads
• ‘thread apply [threadno] [all] args’, a command to apply a command to a list of threads
• thread-specific breakpoints

Warning: These facilities are not yet available on every No value for GDBN configuration where the operating system supports threads. If your No value for GDBN 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:

(No value for GDBP) info threads (No value for GDBP) thread 1 Thread ID 1 not known. Use the "info threads" command to see the IDs of currently known threads.

The No value for GDBN thread debugging facility allows you to observe all threads while your program runs—but whenever No value for GDBN 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 No value for GDBN 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 example, on GNU/Linux, you might see

[New Thread 46912507313328 (LWP 25582)]

when No value for GDBN notices a new thread. In contrast, on an SGI system, the systag is simply something like ‘process 368’, with no further qualifier.

For debugging purposes, No value for GDBN associates its own thread number—always a single integer—with each thread in your program.

info threads

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

1. the thread number assigned by No value for GDBN
2. the target system's thread identifier (systag)
3. the current stack frame summary for that thread

An asterisk ‘*’ to the left of the No value for GDBN thread number indicates the current thread.

For example,

(No value for GDBP) 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, No value for GDBN associates its own thread number—a small integer assigned in thread-creation order—with each thread in your program.

Whenever No value for GDBN detects a new thread in your program, it displays both No value for GDBN'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 No value for GDBN notices a new thread.

info threads

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

1. the thread number assigned by No value for GDBN
2. the target system's thread identifier (systag)
3. the current stack frame summary for that thread

An asterisk ‘*’ to the left of the No value for GDBN thread number indicates the current thread.

For example,

(No value for GDBP) info threads
    * 3 system thread 26607  worker (wptr=0x7b09c318 "@") \

                               at quicksort.c:137
      2 system thread 26606  0x7b0030d8 in __ksleep () \

                               from /usr/lib/libc.2
      1 system thread 27905  0x7b003498 in _brk () \

                               from /usr/lib/libc.2

On Solaris, you can display more information about user threads with a Solaris-specific command:

maint info sol-threads

Display info on Solaris user threads.

thread threadno

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

(No value for GDBP) thread 2 [Switching to process 35 thread 23] 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] command

The thread apply command allows you to apply the named command to one or more threads. Specify the numbers of the threads that you want affected with the command argument threadno. It can be a single thread number, one of the numbers shown in the first field of the ‘info threads’ display; or it could be a range of thread numbers, as in 2-4. To apply a command to all threads, type thread apply all command.

Whenever No value for GDBN stops your program, due to a breakpoint or a signal, it automatically selects the thread where that breakpoint or signal happened. No value for GDBN alerts you to the context switch with a message of the form ‘[Switching to systag]’ to identify the thread.

See section Stopping and Starting Multi-thread Programs, for more information about how No value for GDBN behaves when you stop and start programs with multiple threads.

See section Setting Watchpoints, for information about watchpoints in programs with multiple threads.