1<html lang="en"> 2<head> 3<title>Inferiors and Programs - 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="Kill-Process.html#Kill-Process" title="Kill Process"> 10<link rel="next" href="Threads.html#Threads" title="Threads"> 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="Inferiors-and-Programs"></a> 43<p> 44Next: <a rel="next" accesskey="n" href="Threads.html#Threads">Threads</a>, 45Previous: <a rel="previous" accesskey="p" href="Kill-Process.html#Kill-Process">Kill Process</a>, 46Up: <a rel="up" accesskey="u" href="Running.html#Running">Running</a> 47<hr> 48</div> 49 50<h3 class="section">4.9 Debugging Multiple Inferiors and Programs</h3> 51 52<p><span class="sc">gdb</span> lets you run and debug multiple programs in a single 53session. In addition, <span class="sc">gdb</span> on some systems may let you run 54several programs simultaneously (otherwise you have to exit from one 55before starting another). In the most general case, you can have 56multiple threads of execution in each of multiple processes, launched 57from multiple executables. 58 59 <p><a name="index-inferior-145"></a><span class="sc">gdb</span> represents the state of each program execution with an 60object called an <dfn>inferior</dfn>. An inferior typically corresponds to 61a process, but is more general and applies also to targets that do not 62have processes. Inferiors may be created before a process runs, and 63may be retained after a process exits. Inferiors have unique 64identifiers that are different from process ids. Usually each 65inferior will also have its own distinct address space, although some 66embedded targets may have several inferiors running in different parts 67of a single address space. Each inferior may in turn have multiple 68threads running in it. 69 70 <p>To find out what inferiors exist at any moment, use <code>info inferiors</code><!-- /@w -->: 71 72 73<a name="index-info-inferiors-146"></a> 74<dl><dt><code>info inferiors</code><dd>Print a list of all inferiors currently being managed by <span class="sc">gdb</span>. 75 76 <p><span class="sc">gdb</span> displays for each inferior (in this order): 77 78 <ol type=1 start=1> 79<li>the inferior number assigned by <span class="sc">gdb</span> 80 81 <li>the target system's inferior identifier 82 83 <li>the name of the executable the inferior is running. 84 85 </ol> 86 87 <p class="noindent">An asterisk ‘<samp><span class="samp">*</span></samp>’ preceding the <span class="sc">gdb</span> inferior number 88indicates the current inferior. 89 90 <p>For example, 91</dl> 92 <!-- end table here to get a little more width for example --> 93 94<pre class="smallexample"> (gdb) info inferiors 95 Num Description Executable 96 2 process 2307 hello 97 * 1 process 3401 goodbye 98</pre> 99 <p>To switch focus between inferiors, use the <code>inferior</code> command: 100 101 102<a name="index-inferior-_0040var_007binfno_007d-147"></a> 103<dl><dt><code>inferior </code><var>infno</var><dd>Make inferior number <var>infno</var> the current inferior. The argument 104<var>infno</var> is the inferior number assigned by <span class="sc">gdb</span>, as shown 105in the first field of the ‘<samp><span class="samp">info inferiors</span></samp>’ display. 106</dl> 107 108 <p>You can get multiple executables into a debugging session via the 109<code>add-inferior</code> and <code>clone-inferior</code><!-- /@w --> commands. On some 110systems <span class="sc">gdb</span> can add inferiors to the debug session 111automatically by following calls to <code>fork</code> and <code>exec</code>. To 112remove inferiors from the debugging session use the 113<code>remove-inferiors</code><!-- /@w --> command. 114 115 116<a name="index-add_002dinferior-148"></a> 117<dl><dt><code>add-inferior [ -copies </code><var>n</var><code> ] [ -exec </code><var>executable</var><code> ]</code><dd>Adds <var>n</var> inferiors to be run using <var>executable</var> as the 118executable. <var>n</var> defaults to 1. If no executable is specified, 119the inferiors begins empty, with no program. You can still assign or 120change the program assigned to the inferior at any time by using the 121<code>file</code> command with the executable name as its argument. 122 123 <p><a name="index-clone_002dinferior-149"></a><br><dt><code>clone-inferior [ -copies </code><var>n</var><code> ] [ </code><var>infno</var><code> ]</code><dd>Adds <var>n</var> inferiors ready to execute the same program as inferior 124<var>infno</var>. <var>n</var> defaults to 1. <var>infno</var> defaults to the 125number of the current inferior. This is a convenient command when you 126want to run another instance of the inferior you are debugging. 127 128 <pre class="smallexample"> (gdb) info inferiors 129 Num Description Executable 130 * 1 process 29964 helloworld 131 (gdb) clone-inferior 132 Added inferior 2. 133 1 inferiors added. 134 (gdb) info inferiors 135 Num Description Executable 136 2 <null> helloworld 137 * 1 process 29964 helloworld 138</pre> 139 <p>You can now simply switch focus to inferior 2 and run it. 140 141 <p><a name="index-remove_002dinferiors-150"></a><br><dt><code>remove-inferiors </code><var>infno</var><code>...</code><dd>Removes the inferior or inferiors <var>infno</var><small class="dots">...</small>. It is not 142possible to remove an inferior that is running with this command. For 143those, use the <code>kill</code> or <code>detach</code> command first. 144 145 </dl> 146 147 <p>To quit debugging one of the running inferiors that is not the current 148inferior, you can either detach from it by using the <code>detach inferior</code><!-- /@w --> command (allowing it to run independently), or kill it 149using the <code>kill inferiors</code><!-- /@w --> command: 150 151 152<a name="index-detach-inferiors-_0040var_007binfno_007d_0040dots_007b_007d-151"></a> 153<dl><dt><code>detach inferior </code><var>infno</var><code>...</code><dd>Detach from the inferior or inferiors identified by <span class="sc">gdb</span> 154inferior number(s) <var>infno</var><small class="dots">...</small>. Note that the inferior's entry 155still stays on the list of inferiors shown by <code>info inferiors</code>, 156but its Description will show ‘<samp><span class="samp"><null></span></samp>’. 157 158 <p><a name="index-kill-inferiors-_0040var_007binfno_007d_0040dots_007b_007d-152"></a><br><dt><code>kill inferiors </code><var>infno</var><code>...</code><dd>Kill the inferior or inferiors identified by <span class="sc">gdb</span> inferior 159number(s) <var>infno</var><small class="dots">...</small>. Note that the inferior's entry still 160stays on the list of inferiors shown by <code>info inferiors</code>, but its 161Description will show ‘<samp><span class="samp"><null></span></samp>’. 162</dl> 163 164 <p>After the successful completion of a command such as <code>detach</code>, 165<code>detach inferiors</code>, <code>kill</code> or <code>kill inferiors</code>, or after 166a normal process exit, the inferior is still valid and listed with 167<code>info inferiors</code>, ready to be restarted. 168 169 <p>To be notified when inferiors are started or exit under <span class="sc">gdb</span>'s 170control use <code>set print inferior-events</code><!-- /@w -->: 171 172 173<a name="index-set-print-inferior_002devents-153"></a> 174<a name="index-print-messages-on-inferior-start-and-exit-154"></a> 175<dl><dt><code>set print inferior-events</code><dt><code>set print inferior-events on</code><dt><code>set print inferior-events off</code><dd>The <code>set print inferior-events</code> command allows you to enable or 176disable printing of messages when <span class="sc">gdb</span> notices that new 177inferiors have started or that inferiors have exited or have been 178detached. By default, these messages will not be printed. 179 180 <p><a name="index-show-print-inferior_002devents-155"></a><br><dt><code>show print inferior-events</code><dd>Show whether messages will be printed when <span class="sc">gdb</span> detects that 181inferiors have started, exited or have been detached. 182</dl> 183 184 <p>Many commands will work the same with multiple programs as with a 185single program: e.g., <code>print myglobal</code> will simply display the 186value of <code>myglobal</code> in the current inferior. 187 188 <p>Occasionaly, when debugging <span class="sc">gdb</span> itself, it may be useful to 189get more info about the relationship of inferiors, programs, address 190spaces in a debug session. You can do that with the <code>maint info program-spaces</code><!-- /@w --> command. 191 192 193<a name="index-maint-info-program_002dspaces-156"></a> 194<dl><dt><code>maint info program-spaces</code><dd>Print a list of all program spaces currently being managed by 195<span class="sc">gdb</span>. 196 197 <p><span class="sc">gdb</span> displays for each program space (in this order): 198 199 <ol type=1 start=1> 200<li>the program space number assigned by <span class="sc">gdb</span> 201 202 <li>the name of the executable loaded into the program space, with e.g., 203the <code>file</code> command. 204 205 </ol> 206 207 <p class="noindent">An asterisk ‘<samp><span class="samp">*</span></samp>’ preceding the <span class="sc">gdb</span> program space number 208indicates the current program space. 209 210 <p>In addition, below each program space line, <span class="sc">gdb</span> prints extra 211information that isn't suitable to display in tabular form. For 212example, the list of inferiors bound to the program space. 213 214 <pre class="smallexample"> (gdb) maint info program-spaces 215 Id Executable 216 2 goodbye 217 Bound inferiors: ID 1 (process 21561) 218 * 1 hello 219</pre> 220 <p>Here we can see that no inferior is running the program <code>hello</code>, 221while <code>process 21561</code> is running the program <code>goodbye</code>. On 222some targets, it is possible that multiple inferiors are bound to the 223same program space. The most common example is that of debugging both 224the parent and child processes of a <code>vfork</code> call. For example, 225 226 <pre class="smallexample"> (gdb) maint info program-spaces 227 Id Executable 228 * 1 vfork-test 229 Bound inferiors: ID 2 (process 18050), ID 1 (process 18045) 230</pre> 231 <p>Here, both inferior 2 and inferior 1 are running in the same program 232space as a result of inferior 1 having executed a <code>vfork</code> call. 233</dl> 234 235 </body></html> 236 237