1<html lang="en"> 2<head> 3<title>Threads - Debugging with GDB</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="Debugging with GDB"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="Running.html#Running" title="Running"> 9<link rel="prev" href="Inferiors-and-Programs.html#Inferiors-and-Programs" title="Inferiors and Programs"> 10<link rel="next" href="Forks.html#Forks" title="Forks"> 11<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 12<!-- 13Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 141998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 15Free Software Foundation, Inc. 16 17Permission is granted to copy, distribute and/or modify this document 18under the terms of the GNU Free Documentation License, Version 1.3 or 19any later version published by the Free Software Foundation; with the 20Invariant Sections being ``Free Software'' and ``Free Software Needs 21Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' 22and with the Back-Cover Texts as in (a) below. 23 24(a) The FSF's Back-Cover Text is: ``You are free to copy and modify 25this GNU Manual. Buying copies from GNU Press supports the FSF in 26developing GNU and promoting software freedom.''--> 27<meta http-equiv="Content-Style-Type" content="text/css"> 28<style type="text/css"><!-- 29 pre.display { font-family:inherit } 30 pre.format { font-family:inherit } 31 pre.smalldisplay { font-family:inherit; font-size:smaller } 32 pre.smallformat { font-family:inherit; font-size:smaller } 33 pre.smallexample { font-size:smaller } 34 pre.smalllisp { font-size:smaller } 35 span.sc { font-variant:small-caps } 36 span.roman { font-family:serif; font-weight:normal; } 37 span.sansserif { font-family:sans-serif; font-weight:normal; } 38--></style> 39<link rel="stylesheet" type="text/css" href="../cs.css"> 40</head> 41<body> 42<div class="node"> 43<a name="Threads"></a> 44<p> 45Next: <a rel="next" accesskey="n" href="Forks.html#Forks">Forks</a>, 46Previous: <a rel="previous" accesskey="p" href="Inferiors-and-Programs.html#Inferiors-and-Programs">Inferiors and Programs</a>, 47Up: <a rel="up" accesskey="u" href="Running.html#Running">Running</a> 48<hr> 49</div> 50 51<h3 class="section">4.10 Debugging Programs with Multiple Threads</h3> 52 53<p><a name="index-threads-of-execution-149"></a><a name="index-multiple-threads-150"></a><a name="index-switching-threads-151"></a>In some operating systems, such as HP-UX and Solaris, a single program 54may have more than one <dfn>thread</dfn> of execution. The precise semantics 55of threads differ from one operating system to another, but in general 56the threads of a single program are akin to multiple processes—except 57that they share one address space (that is, they can all examine and 58modify the same variables). On the other hand, each thread has its own 59registers and execution stack, and perhaps private memory. 60 61 <p><span class="sc">gdb</span> provides these facilities for debugging multi-thread 62programs: 63 64 <ul> 65<li>automatic notification of new threads 66<li>‘<samp><span class="samp">thread </span><var>threadno</var></samp>’, a command to switch among threads 67<li>‘<samp><span class="samp">info threads</span></samp>’, a command to inquire about existing threads 68<li>‘<samp><span class="samp">thread apply [</span><var>threadno</var><span class="samp">] [</span><var>all</var><span class="samp">] </span><var>args</var></samp>’, 69a command to apply a command to a list of threads 70<li>thread-specific breakpoints 71<li>‘<samp><span class="samp">set print thread-events</span></samp>’, which controls printing of 72messages on thread start and exit. 73<li>‘<samp><span class="samp">set libthread-db-search-path </span><var>path</var></samp>’, which lets 74the user specify which <code>libthread_db</code> to use if the default choice 75isn't compatible with the program. 76</ul> 77 78 <blockquote> 79<em>Warning:</em> These facilities are not yet available on every 80<span class="sc">gdb</span> configuration where the operating system supports threads. 81If your <span class="sc">gdb</span> does not support threads, these commands have no 82effect. For example, a system without thread support shows no output 83from ‘<samp><span class="samp">info threads</span></samp>’, and always rejects the <code>thread</code> command, 84like this: 85 86<pre class="smallexample"> (gdb) info threads 87 (gdb) thread 1 88 Thread ID 1 not known. Use the "info threads" command to 89 see the IDs of currently known threads. 90</pre> 91 <!-- FIXME to implementors: how hard would it be to say "sorry, this GDB --> 92<!-- doesn't support threads"? --> 93 </blockquote> 94 95 <p><a name="index-focus-of-debugging-152"></a><a name="index-current-thread-153"></a>The <span class="sc">gdb</span> thread debugging facility allows you to observe all 96threads while your program runs—but whenever <span class="sc">gdb</span> takes 97control, one thread in particular is always the focus of debugging. 98This thread is called the <dfn>current thread</dfn>. Debugging commands show 99program information from the perspective of the current thread. 100 101 <p><a name="index-g_t_0040code_007bNew_007d-_0040var_007bsystag_007d-message-154"></a><a name="index-thread-identifier-_0028system_0029-155"></a><!-- FIXME-implementors!! It would be more helpful if the [New...] message --> 102<!-- included GDB's numeric thread handle, so you could just go to that --> 103<!-- thread without first checking `info threads'. --> 104Whenever <span class="sc">gdb</span> detects a new thread in your program, it displays 105the target system's identification for the thread with a message in the 106form ‘<samp><span class="samp">[New </span><var>systag</var><span class="samp">]</span></samp>’. <var>systag</var> is a thread identifier 107whose form varies depending on the particular system. For example, on 108<span class="sc">gnu</span>/Linux, you might see 109 110<pre class="smallexample"> [New Thread 46912507313328 (LWP 25582)] 111</pre> 112 <p class="noindent">when <span class="sc">gdb</span> notices a new thread. In contrast, on an SGI system, 113the <var>systag</var> is simply something like ‘<samp><span class="samp">process 368</span></samp>’, with no 114further qualifier. 115 116<!-- FIXME!! (1) Does the [New...] message appear even for the very first --> 117<!-- thread of a program, or does it only appear for the --> 118<!-- second-i.e.@: when it becomes obvious we have a multithread --> 119<!-- program? --> 120<!-- (2) *Is* there necessarily a first thread always? Or do some --> 121<!-- multithread systems permit starting a program with multiple --> 122<!-- threads ab initio? --> 123 <p><a name="index-thread-number-156"></a><a name="index-thread-identifier-_0028GDB_0029-157"></a>For debugging purposes, <span class="sc">gdb</span> associates its own thread 124number—always a single integer—with each thread in your program. 125 126 127<a name="index-info-threads-158"></a> 128<dl><dt><code>info threads</code><dd>Display a summary of all threads currently in your 129program. <span class="sc">gdb</span> displays for each thread (in this order): 130 131 <ol type=1 start=1> 132<li>the thread number assigned by <span class="sc">gdb</span> 133 134 <li>the target system's thread identifier (<var>systag</var>) 135 136 <li>the current stack frame summary for that thread 137 </ol> 138 139 <p class="noindent">An asterisk ‘<samp><span class="samp">*</span></samp>’ to the left of the <span class="sc">gdb</span> thread number 140indicates the current thread. 141 142 <p>For example, 143</dl> 144 <!-- end table here to get a little more width for example --> 145 146<pre class="smallexample"> (gdb) info threads 147 3 process 35 thread 27 0x34e5 in sigpause () 148 2 process 35 thread 23 0x34e5 in sigpause () 149 * 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8) 150 at threadtest.c:68 151</pre> 152 <p>On HP-UX systems: 153 154 <p><a name="index-debugging-multithreaded-programs-_0028on-HP_002dUX_0029-159"></a><a name="index-thread-identifier-_0028GDB_0029_002c-on-HP_002dUX-160"></a>For debugging purposes, <span class="sc">gdb</span> associates its own thread 155number—a small integer assigned in thread-creation order—with each 156thread in your program. 157 158 <p><a name="index-g_t_0040code_007bNew_007d-_0040var_007bsystag_007d-message_002c-on-HP_002dUX-161"></a><a name="index-thread-identifier-_0028system_0029_002c-on-HP_002dUX-162"></a><!-- FIXME-implementors!! It would be more helpful if the [New...] message --> 159<!-- included GDB's numeric thread handle, so you could just go to that --> 160<!-- thread without first checking `info threads'. --> 161Whenever <span class="sc">gdb</span> detects a new thread in your program, it displays 162both <span class="sc">gdb</span>'s thread number and the target system's identification for the thread with a message in the 163form ‘<samp><span class="samp">[New </span><var>systag</var><span class="samp">]</span></samp>’. <var>systag</var> is a thread identifier 164whose form varies depending on the particular system. For example, on 165HP-UX, you see 166 167<pre class="smallexample"> [New thread 2 (system thread 26594)] 168</pre> 169 <p class="noindent">when <span class="sc">gdb</span> notices a new thread. 170 171 172<a name="index-info-threads-_0028HP_002dUX_0029-163"></a> 173<dl><dt><code>info threads</code><dd>Display a summary of all threads currently in your 174program. <span class="sc">gdb</span> displays for each thread (in this order): 175 176 <ol type=1 start=1> 177<li>the thread number assigned by <span class="sc">gdb</span> 178 179 <li>the target system's thread identifier (<var>systag</var>) 180 181 <li>the current stack frame summary for that thread 182 </ol> 183 184 <p class="noindent">An asterisk ‘<samp><span class="samp">*</span></samp>’ to the left of the <span class="sc">gdb</span> thread number 185indicates the current thread. 186 187 <p>For example, 188</dl> 189 <!-- end table here to get a little more width for example --> 190 191<pre class="smallexample"> (gdb) info threads 192 * 3 system thread 26607 worker (wptr=0x7b09c318 "@") \<br> 193 at quicksort.c:137 194 2 system thread 26606 0x7b0030d8 in __ksleep () \<br> 195 from /usr/lib/libc.2 196 1 system thread 27905 0x7b003498 in _brk () \<br> 197 from /usr/lib/libc.2 198</pre> 199 <p>On Solaris, you can display more information about user threads with a 200Solaris-specific command: 201 202 <dl> 203<dt><code>maint info sol-threads</code><dd><a name="index-maint-info-sol_002dthreads-164"></a><a name="index-thread-info-_0028Solaris_0029-165"></a>Display info on Solaris user threads. 204</dl> 205 206 207<a name="index-thread-_0040var_007bthreadno_007d-166"></a> 208<dl><dt><code>thread </code><var>threadno</var><dd>Make thread number <var>threadno</var> the current thread. The command 209argument <var>threadno</var> is the internal <span class="sc">gdb</span> thread number, as 210shown in the first field of the ‘<samp><span class="samp">info threads</span></samp>’ display. 211<span class="sc">gdb</span> responds by displaying the system identifier of the thread 212you selected, and its current stack frame summary: 213 214 <pre class="smallexample"> <!-- FIXME!! This example made up; find a @value{GDBN} w/threads and get real one --> 215 (gdb) thread 2 216 [Switching to process 35 thread 23] 217 0x34e5 in sigpause () 218</pre> 219 <p class="noindent">As with the ‘<samp><span class="samp">[New ...]</span></samp>’ message, the form of the text after 220‘<samp><span class="samp">Switching to</span></samp>’ depends on your system's conventions for identifying 221threads. 222 223 <p><a name="index-g_t_0024_005fthread_0040r_007b_002c-convenience-variable_007d-167"></a>The debugger convenience variable ‘<samp><span class="samp">$_thread</span></samp>’ contains the number 224of the current thread. You may find this useful in writing breakpoint 225conditional expressions, command scripts, and so forth. See 226See <a href="Convenience-Vars.html#Convenience-Vars">Convenience Variables</a>, for general 227information on convenience variables. 228 229 <p><a name="index-thread-apply-168"></a><a name="index-apply-command-to-several-threads-169"></a><br><dt><code>thread apply [</code><var>threadno</var><code>] [</code><var>all</var><code>] </code><var>command</var><dd>The <code>thread apply</code> command allows you to apply the named 230<var>command</var> to one or more threads. Specify the numbers of the 231threads that you want affected with the command argument 232<var>threadno</var>. It can be a single thread number, one of the numbers 233shown in the first field of the ‘<samp><span class="samp">info threads</span></samp>’ display; or it 234could be a range of thread numbers, as in <code>2-4</code>. To apply a 235command to all threads, type <kbd>thread apply all </kbd><var>command</var>. 236 237 <p><a name="index-set-print-thread_002devents-170"></a><a name="index-print-messages-on-thread-start-and-exit-171"></a><br><dt><code>set print thread-events</code><dt><code>set print thread-events on</code><dt><code>set print thread-events off</code><dd>The <code>set print thread-events</code> command allows you to enable or 238disable printing of messages when <span class="sc">gdb</span> notices that new threads have 239started or that threads have exited. By default, these messages will 240be printed if detection of these events is supported by the target. 241Note that these messages cannot be disabled on all targets. 242 243 <p><a name="index-show-print-thread_002devents-172"></a><br><dt><code>show print thread-events</code><dd>Show whether messages will be printed when <span class="sc">gdb</span> detects that threads 244have started and exited. 245</dl> 246 247 <p>See <a href="Thread-Stops.html#Thread-Stops">Stopping and Starting Multi-thread Programs</a>, for 248more information about how <span class="sc">gdb</span> behaves when you stop and start 249programs with multiple threads. 250 251 <p>See <a href="Set-Watchpoints.html#Set-Watchpoints">Setting Watchpoints</a>, for information about 252watchpoints in programs with multiple threads. 253 254 255<a name="index-set-libthread_002ddb_002dsearch_002dpath-173"></a> 256<a name="index-search-path-for-_0040code_007blibthread_005fdb_007d-174"></a> 257<dl><dt><code>set libthread-db-search-path </code><span class="roman">[</span><var>path</var><span class="roman">]</span><dd>If this variable is set, <var>path</var> is a colon-separated list of 258directories <span class="sc">gdb</span> will use to search for <code>libthread_db</code>. 259If you omit <var>path</var>, ‘<samp><span class="samp">libthread-db-search-path</span></samp>’ will be reset to 260an empty list. 261 262 <p>On <span class="sc">gnu</span>/Linux and Solaris systems, <span class="sc">gdb</span> uses a “helper” 263<code>libthread_db</code> library to obtain information about threads in the 264inferior process. <span class="sc">gdb</span> will use ‘<samp><span class="samp">libthread-db-search-path</span></samp>’ 265to find <code>libthread_db</code>. If that fails, <span class="sc">gdb</span> will continue 266with default system shared library directories, and finally the directory 267from which <code>libpthread</code> was loaded in the inferior process. 268 269 <p>For any <code>libthread_db</code> library <span class="sc">gdb</span> finds in above directories, 270<span class="sc">gdb</span> attempts to initialize it with the current inferior process. 271If this initialization fails (which could happen because of a version 272mismatch between <code>libthread_db</code> and <code>libpthread</code>), <span class="sc">gdb</span> 273will unload <code>libthread_db</code>, and continue with the next directory. 274If none of <code>libthread_db</code> libraries initialize successfully, 275<span class="sc">gdb</span> will issue a warning and thread debugging will be disabled. 276 277 <p>Setting <code>libthread-db-search-path</code> is currently implemented 278only on some platforms. 279 280 <p><a name="index-show-libthread_002ddb_002dsearch_002dpath-175"></a><br><dt><code>show libthread-db-search-path</code><dd>Display current libthread_db search path. 281 282 <p><a name="index-set-debug-libthread_002ddb-176"></a><a name="index-show-debug-libthread_002ddb-177"></a><a name="index-debugging-_0040code_007blibthread_005fdb_007d-178"></a><br><dt><code>set debug libthread-db</code><dt><code>show debug libthread-db</code><dd>Turns on or off display of <code>libthread_db</code>-related events. 283Use <code>1</code> to enable, <code>0</code> to disable. 284</dl> 285 286 </body></html> 287 288