Inferiors-and-Programs.html 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317
  1. <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
  2. <html>
  3. <!-- Copyright (C) 1988-2019 Free Software Foundation, Inc.
  4. Permission is granted to copy, distribute and/or modify this document
  5. under the terms of the GNU Free Documentation License, Version 1.3 or
  6. any later version published by the Free Software Foundation; with the
  7. Invariant Sections being "Free Software" and "Free Software Needs
  8. Free Documentation", with the Front-Cover Texts being "A GNU Manual,"
  9. and with the Back-Cover Texts as in (a) below.
  10. (a) The FSF's Back-Cover Text is: "You are free to copy and modify
  11. this GNU Manual. Buying copies from GNU Press supports the FSF in
  12. developing GNU and promoting software freedom." -->
  13. <!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
  14. <head>
  15. <title>Debugging with GDB: Inferiors and Programs</title>
  16. <meta name="description" content="Debugging with GDB: Inferiors and Programs">
  17. <meta name="keywords" content="Debugging with GDB: Inferiors and Programs">
  18. <meta name="resource-type" content="document">
  19. <meta name="distribution" content="global">
  20. <meta name="Generator" content="makeinfo">
  21. <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  22. <link href="index.html#Top" rel="start" title="Top">
  23. <link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
  24. <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
  25. <link href="Running.html#Running" rel="up" title="Running">
  26. <link href="Threads.html#Threads" rel="next" title="Threads">
  27. <link href="Kill-Process.html#Kill-Process" rel="prev" title="Kill Process">
  28. <style type="text/css">
  29. <!--
  30. a.summary-letter {text-decoration: none}
  31. blockquote.smallquotation {font-size: smaller}
  32. div.display {margin-left: 3.2em}
  33. div.example {margin-left: 3.2em}
  34. div.indentedblock {margin-left: 3.2em}
  35. div.lisp {margin-left: 3.2em}
  36. div.smalldisplay {margin-left: 3.2em}
  37. div.smallexample {margin-left: 3.2em}
  38. div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
  39. div.smalllisp {margin-left: 3.2em}
  40. kbd {font-style:oblique}
  41. pre.display {font-family: inherit}
  42. pre.format {font-family: inherit}
  43. pre.menu-comment {font-family: serif}
  44. pre.menu-preformatted {font-family: serif}
  45. pre.smalldisplay {font-family: inherit; font-size: smaller}
  46. pre.smallexample {font-size: smaller}
  47. pre.smallformat {font-family: inherit; font-size: smaller}
  48. pre.smalllisp {font-size: smaller}
  49. span.nocodebreak {white-space:nowrap}
  50. span.nolinebreak {white-space:nowrap}
  51. span.roman {font-family:serif; font-weight:normal}
  52. span.sansserif {font-family:sans-serif; font-weight:normal}
  53. ul.no-bullet {list-style: none}
  54. -->
  55. </style>
  56. </head>
  57. <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
  58. <a name="Inferiors-and-Programs"></a>
  59. <div class="header">
  60. <p>
  61. Next: <a href="Threads.html#Threads" accesskey="n" rel="next">Threads</a>, Previous: <a href="Kill-Process.html#Kill-Process" accesskey="p" rel="prev">Kill Process</a>, Up: <a href="Running.html#Running" accesskey="u" rel="up">Running</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
  62. </div>
  63. <hr>
  64. <a name="Debugging-Multiple-Inferiors-and-Programs"></a>
  65. <h3 class="section">4.9 Debugging Multiple Inferiors and Programs</h3>
  66. <p><small>GDB</small> lets you run and debug multiple programs in a single
  67. session. In addition, <small>GDB</small> on some systems may let you run
  68. several programs simultaneously (otherwise you have to exit from one
  69. before starting another). In the most general case, you can have
  70. multiple threads of execution in each of multiple processes, launched
  71. from multiple executables.
  72. </p>
  73. <a name="index-inferior"></a>
  74. <p><small>GDB</small> represents the state of each program execution with an
  75. object called an <em>inferior</em>. An inferior typically corresponds to
  76. a process, but is more general and applies also to targets that do not
  77. have processes. Inferiors may be created before a process runs, and
  78. may be retained after a process exits. Inferiors have unique
  79. identifiers that are different from process ids. Usually each
  80. inferior will also have its own distinct address space, although some
  81. embedded targets may have several inferiors running in different parts
  82. of a single address space. Each inferior may in turn have multiple
  83. threads running in it.
  84. </p>
  85. <p>To find out what inferiors exist at any moment, use <code>info&nbsp;inferiors</code><!-- /@w -->:
  86. </p>
  87. <dl compact="compact">
  88. <dd><a name="index-info-inferiors-_005b-id_2026-_005d"></a>
  89. </dd>
  90. <dt><code>info inferiors</code></dt>
  91. <dd><p>Print a list of all inferiors currently being managed by <small>GDB</small>.
  92. By default all inferiors are printed, but the argument <var>id</var>&hellip;
  93. &ndash; a space separated list of inferior numbers &ndash; can be used to limit
  94. the display to just the requested inferiors.
  95. </p>
  96. <p><small>GDB</small> displays for each inferior (in this order):
  97. </p>
  98. <ol>
  99. <li> the inferior number assigned by <small>GDB</small>
  100. </li><li> the target system&rsquo;s inferior identifier
  101. </li><li> the name of the executable the inferior is running.
  102. </li></ol>
  103. <p>An asterisk &lsquo;<samp>*</samp>&rsquo; preceding the <small>GDB</small> inferior number
  104. indicates the current inferior.
  105. </p>
  106. <p>For example,
  107. </p></dd>
  108. </dl>
  109. <div class="smallexample">
  110. <pre class="smallexample">(gdb) info inferiors
  111. Num Description Executable
  112. 2 process 2307 hello
  113. * 1 process 3401 goodbye
  114. </pre></div>
  115. <p>To switch focus between inferiors, use the <code>inferior</code> command:
  116. </p>
  117. <dl compact="compact">
  118. <dd><a name="index-inferior-infno"></a>
  119. </dd>
  120. <dt><code>inferior <var>infno</var></code></dt>
  121. <dd><p>Make inferior number <var>infno</var> the current inferior. The argument
  122. <var>infno</var> is the inferior number assigned by <small>GDB</small>, as shown
  123. in the first field of the &lsquo;<samp>info inferiors</samp>&rsquo; display.
  124. </p></dd>
  125. </dl>
  126. <a name="index-_0024_005finferior_002c-convenience-variable"></a>
  127. <p>The debugger convenience variable &lsquo;<samp>$_inferior</samp>&rsquo; contains the
  128. number of the current inferior. You may find this useful in writing
  129. breakpoint conditional expressions, command scripts, and so forth.
  130. See <a href="Convenience-Vars.html#Convenience-Vars">Convenience Variables</a>, for general
  131. information on convenience variables.
  132. </p>
  133. <p>You can get multiple executables into a debugging session via the
  134. <code>add-inferior</code> and <code><span class="nolinebreak">clone-inferior</span></code><!-- /@w --> commands. On some
  135. systems <small>GDB</small> can add inferiors to the debug session
  136. automatically by following calls to <code>fork</code> and <code>exec</code>. To
  137. remove inferiors from the debugging session use the
  138. <code><span class="nolinebreak">remove-inferiors</span></code><!-- /@w --> command.
  139. </p>
  140. <dl compact="compact">
  141. <dd><a name="index-add_002dinferior"></a>
  142. </dd>
  143. <dt><code>add-inferior [ -copies <var>n</var> ] [ -exec <var>executable</var> ]</code></dt>
  144. <dd><p>Adds <var>n</var> inferiors to be run using <var>executable</var> as the
  145. executable; <var>n</var> defaults to 1. If no executable is specified,
  146. the inferiors begins empty, with no program. You can still assign or
  147. change the program assigned to the inferior at any time by using the
  148. <code>file</code> command with the executable name as its argument.
  149. </p>
  150. <a name="index-clone_002dinferior"></a>
  151. </dd>
  152. <dt><code>clone-inferior [ -copies <var>n</var> ] [ <var>infno</var> ]</code></dt>
  153. <dd><p>Adds <var>n</var> inferiors ready to execute the same program as inferior
  154. <var>infno</var>; <var>n</var> defaults to 1, and <var>infno</var> defaults to the
  155. number of the current inferior. This is a convenient command when you
  156. want to run another instance of the inferior you are debugging.
  157. </p>
  158. <div class="smallexample">
  159. <pre class="smallexample">(gdb) info inferiors
  160. Num Description Executable
  161. * 1 process 29964 helloworld
  162. (gdb) clone-inferior
  163. Added inferior 2.
  164. 1 inferiors added.
  165. (gdb) info inferiors
  166. Num Description Executable
  167. 2 &lt;null&gt; helloworld
  168. * 1 process 29964 helloworld
  169. </pre></div>
  170. <p>You can now simply switch focus to inferior 2 and run it.
  171. </p>
  172. <a name="index-remove_002dinferiors"></a>
  173. </dd>
  174. <dt><code>remove-inferiors <var>infno</var>&hellip;</code></dt>
  175. <dd><p>Removes the inferior or inferiors <var>infno</var>&hellip;. It is not
  176. possible to remove an inferior that is running with this command. For
  177. those, use the <code>kill</code> or <code>detach</code> command first.
  178. </p>
  179. </dd>
  180. </dl>
  181. <p>To quit debugging one of the running inferiors that is not the current
  182. inferior, you can either detach from it by using the <code>detach&nbsp;inferior</code><!-- /@w --> command (allowing it to run independently), or kill it
  183. using the <code>kill&nbsp;inferiors</code><!-- /@w --> command:
  184. </p>
  185. <dl compact="compact">
  186. <dd><a name="index-detach-inferiors-infno_2026"></a>
  187. </dd>
  188. <dt><code>detach inferior <var>infno</var>&hellip;</code></dt>
  189. <dd><p>Detach from the inferior or inferiors identified by <small>GDB</small>
  190. inferior number(s) <var>infno</var>&hellip;. Note that the inferior&rsquo;s entry
  191. still stays on the list of inferiors shown by <code>info inferiors</code>,
  192. but its Description will show &lsquo;<samp>&lt;null&gt;</samp>&rsquo;.
  193. </p>
  194. <a name="index-kill-inferiors-infno_2026"></a>
  195. </dd>
  196. <dt><code>kill inferiors <var>infno</var>&hellip;</code></dt>
  197. <dd><p>Kill the inferior or inferiors identified by <small>GDB</small> inferior
  198. number(s) <var>infno</var>&hellip;. Note that the inferior&rsquo;s entry still
  199. stays on the list of inferiors shown by <code>info inferiors</code>, but its
  200. Description will show &lsquo;<samp>&lt;null&gt;</samp>&rsquo;.
  201. </p></dd>
  202. </dl>
  203. <p>After the successful completion of a command such as <code>detach</code>,
  204. <code>detach inferiors</code>, <code>kill</code> or <code>kill inferiors</code>, or after
  205. a normal process exit, the inferior is still valid and listed with
  206. <code>info inferiors</code>, ready to be restarted.
  207. </p>
  208. <p>To be notified when inferiors are started or exit under <small>GDB</small>&rsquo;s
  209. control use <code>set&nbsp;print&nbsp;<span class="nolinebreak">inferior-events</span></code><!-- /@w -->:
  210. </p>
  211. <dl compact="compact">
  212. <dd><a name="index-set-print-inferior_002devents"></a>
  213. <a name="index-print-messages-on-inferior-start-and-exit"></a>
  214. </dd>
  215. <dt><code>set print inferior-events</code></dt>
  216. <dt><code>set print inferior-events on</code></dt>
  217. <dt><code>set print inferior-events off</code></dt>
  218. <dd><p>The <code>set print inferior-events</code> command allows you to enable or
  219. disable printing of messages when <small>GDB</small> notices that new
  220. inferiors have started or that inferiors have exited or have been
  221. detached. By default, these messages will not be printed.
  222. </p>
  223. <a name="index-show-print-inferior_002devents"></a>
  224. </dd>
  225. <dt><code>show print inferior-events</code></dt>
  226. <dd><p>Show whether messages will be printed when <small>GDB</small> detects that
  227. inferiors have started, exited or have been detached.
  228. </p></dd>
  229. </dl>
  230. <p>Many commands will work the same with multiple programs as with a
  231. single program: e.g., <code>print myglobal</code> will simply display the
  232. value of <code>myglobal</code> in the current inferior.
  233. </p>
  234. <p>Occasionaly, when debugging <small>GDB</small> itself, it may be useful to
  235. get more info about the relationship of inferiors, programs, address
  236. spaces in a debug session. You can do that with the <code>maint&nbsp;info&nbsp;<span class="nolinebreak">program-spaces</span></code><!-- /@w --> command.
  237. </p>
  238. <dl compact="compact">
  239. <dd><a name="index-maint-info-program_002dspaces"></a>
  240. </dd>
  241. <dt><code>maint info program-spaces</code></dt>
  242. <dd><p>Print a list of all program spaces currently being managed by
  243. <small>GDB</small>.
  244. </p>
  245. <p><small>GDB</small> displays for each program space (in this order):
  246. </p>
  247. <ol>
  248. <li> the program space number assigned by <small>GDB</small>
  249. </li><li> the name of the executable loaded into the program space, with e.g.,
  250. the <code>file</code> command.
  251. </li></ol>
  252. <p>An asterisk &lsquo;<samp>*</samp>&rsquo; preceding the <small>GDB</small> program space number
  253. indicates the current program space.
  254. </p>
  255. <p>In addition, below each program space line, <small>GDB</small> prints extra
  256. information that isn&rsquo;t suitable to display in tabular form. For
  257. example, the list of inferiors bound to the program space.
  258. </p>
  259. <div class="smallexample">
  260. <pre class="smallexample">(gdb) maint info program-spaces
  261. Id Executable
  262. * 1 hello
  263. 2 goodbye
  264. Bound inferiors: ID 1 (process 21561)
  265. </pre></div>
  266. <p>Here we can see that no inferior is running the program <code>hello</code>,
  267. while <code>process 21561</code> is running the program <code>goodbye</code>. On
  268. some targets, it is possible that multiple inferiors are bound to the
  269. same program space. The most common example is that of debugging both
  270. the parent and child processes of a <code>vfork</code> call. For example,
  271. </p>
  272. <div class="smallexample">
  273. <pre class="smallexample">(gdb) maint info program-spaces
  274. Id Executable
  275. * 1 vfork-test
  276. Bound inferiors: ID 2 (process 18050), ID 1 (process 18045)
  277. </pre></div>
  278. <p>Here, both inferior 2 and inferior 1 are running in the same program
  279. space as a result of inferior 1 having executed a <code>vfork</code> call.
  280. </p></dd>
  281. </dl>
  282. <hr>
  283. <div class="header">
  284. <p>
  285. Next: <a href="Threads.html#Threads" accesskey="n" rel="next">Threads</a>, Previous: <a href="Kill-Process.html#Kill-Process" accesskey="p" rel="prev">Kill Process</a>, Up: <a href="Running.html#Running" accesskey="u" rel="up">Running</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
  286. </div>
  287. </body>
  288. </html>