mingw/info/gdb/Threads.html

   1 <html lang="en">
   2 <head>
   3 <title>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.3">
   7 <link href="http://www.gnu.org/software/texinfo/" rel="generator-home">
   8 </head>
   9 <body>
  10 <div class="node">
  11 <p>
  12 Node:<a name="Threads">Threads</a>,
  13 Next:<a rel="next" accesskey="n" href="Processes.html#Processes">Processes</a>,
  14 Previous:<a rel="previous" accesskey="p" href="Kill-Process.html#Kill%20Process">Kill Process</a>,
  15 Up:<a rel="up" accesskey="u" href="Running.html#Running">Running</a>
  16 <hr><br>
  17 </div>
  18
  19 <h3 class="section">Debugging programs with multiple threads</h3>
  20
  21    <p>In some operating systems, such as HP-UX and Solaris, a single program
  22 may have more than one <dfn>thread</dfn> of execution.  The precise semantics
  23 of threads differ from one operating system to another, but in general
  24 the threads of a single program are akin to multiple processes--except
  25 that they share one address space (that is, they can all examine and
  26 modify the same variables).  On the other hand, each thread has its own
  27 registers and execution stack, and perhaps private memory.
  28
  29    GDB provides these facilities for debugging multi-thread
  30 programs:
  31
  32      <ul>
  33 <li>automatic notification of new threads
  34 <li><code>thread </code><var>threadno</var><code></code>, a command to switch among threads
  35 <li><code>info threads</code>, a command to inquire about existing threads
  36 <li><code>thread apply [</code><var>threadno</var><code>] [</code><var>all</var><code>] </code><var>args</var><code></code>,
  37 a command to apply a command to a list of threads
  38 <li>thread-specific breakpoints
  39 </ul>
  40
  41    <blockquote>
  42 <em>Warning:</em> These facilities are not yet available on every
  43 GDB configuration where the operating system supports threads.
  44 If your GDB does not support threads, these commands have no
  45 effect.  For example, a system without thread support shows no output
  46 from <code>info threads</code>, and always rejects the <code>thread</code> command,
  47 like this:
  48
  49      <pre class="smallexample">          (gdb) info threads
  50           (gdb) thread 1
  51           Thread ID 1 not known.  Use the "info threads" command to
  52           see the IDs of currently known threads.
  53           </pre>
  54         </blockquote>
  55
  56    <p>The GDB thread debugging facility allows you to observe all
  57 threads while your program runs--but whenever GDB takes
  58 control, one thread in particular is always the focus of debugging.
  59 This thread is called the <dfn>current thread</dfn>.  Debugging commands show
  60 program information from the perspective of the current thread.
  61
  62    <p>Whenever GDB detects a new thread in your program, it displays
  63 the target system's identification for the thread with a message in the
  64 form <code>[New </code><var>systag</var><code>]</code>.  <var>systag</var> is a thread identifier
  65 whose form varies depending on the particular system.  For example, on
  66 LynxOS, you might see
  67
  68 <pre class="example">     [New process 35 thread 27]
  69      </pre>
  70
  71 <p>when GDB notices a new thread.  In contrast, on an SGI system,
  72 the <var>systag</var> is simply something like <code>process 368</code>, with no
  73 further qualifier.
  74
  75    <p>For debugging purposes, GDB associates its own thread
  76 number--always a single integer--with each thread in your program.
  77
  78      <dl>
  79 <dt><code>info threads</code>
  80      <dd>Display a summary of all threads currently in your
  81 program.  GDB displays for each thread (in this order):
  82
  83           <ol type=1 start=1>
  84 <li>the thread number assigned by GDB
  85
  86           <li>the target system's thread identifier (<var>systag</var>)
  87
  88           <li>the current stack frame summary for that thread
  89           </ol>
  90
  91      <p>An asterisk <code>*</code> to the left of the GDB thread number
  92 indicates the current thread.
  93
  94      <p>For example,
  95 </dl>
  96
  97 <pre class="smallexample">     (gdb) info threads
  98        3 process 35 thread 27  0x34e5 in sigpause ()
  99        2 process 35 thread 23  0x34e5 in sigpause ()
 100      * 1 process 35 thread 13  main (argc=1, argv=0x7ffffff8)
 101          at threadtest.c:68
 102      </pre>
 103
 104    <p>On HP-UX systems:
 105
 106    <p>For debugging purposes, GDB associates its own thread
 107 number--a small integer assigned in thread-creation order--with each
 108 thread in your program.
 109
 110    <p>Whenever GDB detects a new thread in your program, it displays
 111 both GDB's thread number and the target system's identification for the thread with a message in the
 112 form <code>[New </code><var>systag</var><code>]</code>.  <var>systag</var> is a thread identifier
 113 whose form varies depending on the particular system.  For example, on
 114 HP-UX, you see
 115
 116 <pre class="example">     [New thread 2 (system thread 26594)]
 117      </pre>
 118
 119 <p>when GDB notices a new thread.
 120
 121      <dl>
 122 <dt><code>info threads</code>
 123      <dd>Display a summary of all threads currently in your
 124 program.  GDB displays for each thread (in this order):
 125
 126           <ol type=1 start=1>
 127 <li>the thread number assigned by GDB
 128
 129           <li>the target system's thread identifier (<var>systag</var>)
 130
 131           <li>the current stack frame summary for that thread
 132           </ol>
 133
 134      <p>An asterisk <code>*</code> to the left of the GDB thread number
 135 indicates the current thread.
 136
 137      <p>For example,
 138 </dl>
 139
 140 <pre class="example">     (gdb) info threads
 141          * 3 system thread 26607  worker (wptr=0x7b09c318 "@") \<br>
 142                                     at quicksort.c:137
 143            2 system thread 26606  0x7b0030d8 in __ksleep () \<br>
 144                                     from /usr/lib/libc.2
 145            1 system thread 27905  0x7b003498 in _brk () \<br>
 146                                     from /usr/lib/libc.2
 147      </pre>
 148
 149      <dl>
 150 <dt><code>thread </code><var>threadno</var><code></code>
 151      <dd>Make thread number <var>threadno</var> the current thread.  The command
 152 argument <var>threadno</var> is the internal GDB thread number, as
 153 shown in the first field of the <code>info threads</code> display.
 154 GDB responds by displaying the system identifier of the thread
 155 you selected, and its current stack frame summary:
 156
 157      <pre class="smallexample">          (gdb) thread 2
 158           [Switching to process 35 thread 23]
 159           0x34e5 in sigpause ()
 160           </pre>
 161
 162      <p>As with the <code>[New ...]</code> message, the form of the text after
 163 <code>Switching to</code> depends on your system's conventions for identifying
 164 threads.
 165
 166      <br><dt><code>thread apply [</code><var>threadno</var><code>] [</code><var>all</var><code>]  </code><var>args</var><code></code>
 167      <dd>The <code>thread apply</code> command allows you to apply a command to one or
 168 more threads.  Specify the numbers of the threads that you want affected
 169 with the command argument <var>threadno</var>.  <var>threadno</var> is the internal
 170 GDB thread number, as shown in the first field of the <code>info
 171 threads</code> display.  To apply a command to all threads, use
 172 <code>thread apply all</code> <var>args</var>.
 173 </dl>
 174
 175    <p>Whenever GDB stops your program, due to a breakpoint or a
 176 signal, it automatically selects the thread where that breakpoint or
 177 signal happened.  GDB alerts you to the context switch with a
 178 message of the form <code>[Switching to </code><var>systag</var><code>]</code> to identify the
 179 thread.
 180
 181    <p>See <a href="Thread-Stops.html#Thread%20Stops">Stopping and starting multi-thread programs</a>, for
 182 more information about how GDB behaves when you stop and start
 183 programs with multiple threads.
 184
 185    <p>See <a href="Set-Watchpoints.html#Set%20Watchpoints">Setting watchpoints</a>, for information about
 186 watchpoints in programs with multiple threads.
 187
 188    </body></html>
 189