Debugging Programs with Multiple Threads

In some operating systems, such as HP-UX and Solaris, a single program may have more than one threadof 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 threadhas its own registers and execution stack, and perhaps private memory.

gdb provides these facilities for debugging multi-threadprograms:

automatic notification of new threads

`threadthreadno', a command to switch among threads

`info threads', a command to inquire about existing threads

`threadapply [threadno][all]args', a command to apply a command to a list of threads

thread-specific breakpoints

`set print thread-events', which controls printing of messages on threadstart and exit.

`set libthread-db-search-pathpath', which lets the user specify which

libthread_db

to use if the default choice isn't compatible with the program.

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 threadsupport shows no output from `info threads', and always rejects the

thread

command, like this:

(gdb) info threads
(gdb) thread1
Thread ID 1 not known.  Use the "info threads" command to
see the IDs of currently known threads.

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

Whenever gdb detects a new threadin your program, it displays the target system's identification for the threadwith a message in the form `[New systag]'. systag is a threadidentifier whose form varies depending on the particular system. For example, on gnu/Linux, you might see

[New Thread 46912507313328 (LWP 25582)]

when gdb 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, gdb associates its own threadnumber—always a single integer—with each threadin your program.

info threads

Display a summary of all threads currently in your program. gdb displays for each thread(in this order): the threadnumber assigned by gdb

the target system's threadidentifier (systag)

the current stack frame summary for that thread

An asterisk `*' to the left of the gdb threadnumber indicates the current thread.
For example,

(gdb) info threads
3 process 35 thread27  0x34e5 in sigpause ()
2 process 35 thread23  0x34e5 in sigpause ()
* 1 process 35 thread13  main (argc=1, argv=0x7ffffff8)
at threadtest.c:68

On HP-UX systems:

For debugging purposes, gdb associates its own threadnumber—a small integer assigned in thread-creation order—with each threadin your program.

Whenever gdb detects a new threadin your program, it displays both gdb's threadnumber and the target system's identification for the threadwith a message in the form `[New systag]'. systag is a threadidentifier whose form varies depending on the particular system. For example, on HP-UX, you see

[New thread2 (system thread26594)]

when gdb notices a new thread.

info threads

Display a summary of all threads currently in your program. gdb displays for each thread(in this order): the threadnumber assigned by gdb

the target system's threadidentifier (systag)

the current stack frame summary for that thread

An asterisk `*' to the left of the gdb threadnumber indicates the current thread.
For example,

(gdb) info threads
* 3 system thread26607  worker (wptr=0x7b09c318 "@") /

at quicksort.c:137
2 system thread26606  0x7b0030d8 in __ksleep () /

from /usr/lib/libc.2
1 system thread27905  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 threadnumber threadno the current thread. The command argument threadno is the internal gdb threadnumber, as shown in the first field of the `info threads' display. gdb responds by displaying the system identifier of the threadyou selected, and its current stack frame summary:

(gdb) thread2
[Switching to process 35 thread23]
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.
The debugger convenience variable `$_thread' contains the number of the current thread. You may find this useful in writing breakpoint conditional expressions, command scripts, and so forth. See See Convenience Variables, for general information on convenience variables.

threadapply [

threadno

][

all

]

command The

threadapply

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 threadnumber, one of the numbers shown in the first field of the `info threads' display; or it could be a range of threadnumbers, as in

2-4

. To apply a command to all threads, type threadapply all command.

set print thread-events

set print thread-events on

set print thread-events off

The

set print thread-events

command allows you to enable or disable printing of messages when gdb notices that new threads have started or that threads have exited. By default, these messages will be printed if detection of these events is supported by the target. Note that these messages cannot be disabled on all targets.

show print thread-events

Show whether messages will be printed when gdb detects that threads have started and exited. See Stopping and Starting Multi-threadPrograms, for more information about how gdb behaves when you stop and start programs with multiple threads.

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

set libthread-db-search-path

[path]If this variable is set, path is a colon-separated list of directories gdb will use to search for

libthread_db

. If you omit path, `libthread-db-search-path' will be reset to an empty list.
On gnu/Linux and Solaris systems, gdb uses a “helper”

libthread_db

library to obtain information about threads in the inferior process. gdb will use `libthread-db-search-path' to find

libthread_db

. If that fails, gdb will continue with default system shared library directories, and finally the directory from which

libpthread

was loaded in the inferior process.

For any

libthread_db

library gdb finds in above directories, gdb attempts to initialize it with the current inferior process. If this initialization fails (which could happen because of a version mismatch between

libthread_db

and

libpthread

), gdb will unload

libthread_db

, and continue with the next directory. If none of

libthread_db

libraries initialize successfully, gdb will issue a warning and threaddebugging will be disabled.

Setting

libthread-db-search-path

is currently implemented only on some platforms.

show libthread-db-search-path

Display current libthread_db search path.

set debug libthread-db

show debug libthread-db

Turns on or off display of

libthread_db

-related events. Use

1

to enable,

0

to disable.  

gdb supports debugging programs with multiple threads (see 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 threadin 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 threadin the debugger.

All-Stop Mode: All threads stop when GDB takes control

Non-Stop Mode: Other threads continue to execute

Background Execution: Running your program asynchronously

Thread-Specific Breakpoints: Controlling breakpoints

Interrupted System Calls: GDB may interfere with system calls

Observer Mode: GDB does not alter program behavior