gdb.info: Threads

Running

Forks

Inferiors and Programs

Back to Software Index

4.10 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.

   GDB 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
   * 'set print thread-events', which controls printing of messages on
     thread start and exit.
   * 'set libthread-db-search-path PATH', 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 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]', where SYSTAG is a thread identifier whose form varies
depending on the particular system.  For example, on GNU/Linux, you
might see

     [New Thread 0x41e02940 (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 thread number--always
a single integer--with each thread in your program.

'info threads [ID...]'
     Display a summary of all threads currently in your program.
     Optional argument ID... is one or more thread ids separated by
     spaces, and means to print information only about the specified
     thread or threads.  GDB displays for each thread (in this order):

       1. the thread number assigned by GDB

       2. the target system's thread identifier (SYSTAG)

       3. the thread's name, if one is known.  A thread can either be
          named by the user (see 'thread name', below), or, in some
          cases, by the program itself.

       4. the current stack frame summary for that thread

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

     For example,

     (gdb) info threads
       Id   Target Id         Frame
       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 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 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 (Thread 0xb7fdab70 (LWP 12747))]
          #0  some_function (ignore=0x0) at example.c:8
          8	    printf ("hello\n");

     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 Note:
     Convenience Variables, for general information on
     convenience variables.

'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'.

'thread name [NAME]'
     This command assigns a name to the current thread.  If no argument
     is given, any existing user-specified name is removed.  The thread
     name appears in the 'info threads' display.

     On some systems, such as GNU/Linux, GDB is able to determine the
     name of the thread as given by the OS. On these systems, a name
     specified with 'thread name' will override the system-give name,
     and removing the user-specified name will cause GDB to once again
     display the system-specified name.

'thread find [REGEXP]'
     Search for and display thread ids whose name or SYSTAG matches the
     supplied regular expression.

     As well as being the complement to the 'thread name' command, this
     command also allows you to identify a thread by its target SYSTAG.
     For instance, on GNU/Linux, the target SYSTAG is the LWP id.

          (GDB) thread find 26688
          Thread 4 has target id 'Thread 0x41e02940 (LWP 26688)'
          (GDB) info thread 4
            Id   Target Id         Frame
            4    Thread 0x41e02940 (LWP 26688) 0x00000031ca6cd372 in select ()

'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.

   Note: Stopping and Starting Multi-thread Programs, for
more information about how GDB behaves when you stop and start programs
with multiple threads.

   Note: 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 its default value
     ('$sdir:$pdir' on GNU/Linux and Solaris systems).  Internally, the
     default value comes from the 'LIBTHREAD_DB_SEARCH_PATH' macro.

     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'.  GDB also consults first if inferior specific
     thread debugging library loading is enabled by 'set auto-load
     libthread-db' (*note libthread_db.so.1 file::).

     A special entry '$sdir' for 'libthread-db-search-path' refers to
     the default system directories that are normally searched for
     loading shared libraries.  The '$sdir' entry is the only kind not
     needing to be enabled by 'set auto-load libthread-db' (*note
     libthread_db.so.1 file::).

     A special entry '$pdir' for 'libthread-db-search-path' refers to
     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 thread debugging 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.