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